Email Delivery Testing With a Resend API Simulator
A stateful simulator tests bounces, webhooks, and suppression in CI.

Integration testing against stateful APIs requires a simulator that preserves the results of earlier calls, so later requests and events act on the same records without hitting production. For Resend, that means testing delivery, bounces, webhooks, and suppression against a stored email. A stateful Resend API simulator makes those workflows testable locally and in CI without live credentials or quota consumption.
Why a 200 OK is not the end of an email integration test
The natural first email integration test sends a request, checks for 200 OK, and moves on. Yet a successful POST /emails proves only that the API accepted the request. It does not prove that the application understands what happens to the email afterward.
The meaningful sequence continues through receiving the sandbox ID, observing delivery status, handling lifecycle webhooks, and updating application state. The final assertion belongs after those state changes. A delivered, bounced, opened, clicked, or complained event gives the application a different outcome to process. A test that ends at acceptance misses suppression that never takes effect, a bounce handler that processes a duplicate twice, and recipient state that stays unchanged after a complaint.
What stateless mocks can and cannot do for email workflows
A hand-written fetch stub is a reasonable starting point for checking an isolated endpoint call. It returns a fixed payload for a matching request, allowing a test to validate how the application handles that response. There is no need for persistent state in every test. The limitation appears when the next operation depends on something the previous operation created.
For example, a stub can return a fake email ID without storing an email. A subsequent GET /emails/{id} therefore has nothing to retrieve unless another response is supplied by hand. That response can match the expected record, but the stub does not establish that the send created it. The same disconnect affects webhooks. Events such as email.delivered, email.bounced, email.opened, and email.clicked must be written and maintained separately rather than generated from changes to the stored email.
Idempotency exposes the same structural limit because remembering an earlier key is part of the behavior under test. A fixed response cannot establish whether a replay was recognized or a duplicate send was created. The distinction is between testing outputs and testing dependencies. Stateless mocks suit isolated endpoint checks, while workflows whose later responses depend on earlier operations need stateful behavior by design.
What the Resend API lifecycle actually looks like across all its surfaces
The lifecycle starts before delivery, with the data and configuration that support sending. The Resend client exposes audiences, broadcasts, contacts, domains, webhooks, templates, and automations in addition to emails. Adding a contact changes what a later list call returns, and removing it must change that list again. These mutations are part of the integration contract.
At the send stage, POST /emails creates an email record and fires email.sent. Acceptance is only the first transition in that record’s lifecycle. Delivery, bouncing, opening, clicking, and complaints each produce separate events for the application to handle. A test that models only message creation does not test any of the event handlers that run afterward.
Resend provides designated addresses for exercising delivery outcomes, including delivered@resend.dev, bounced@resend.dev, complained@resend.dev, and suppressed@resend.dev. Most support plus-label variants such as bounced+signup@resend.dev, which distinguish scenarios across webhook responses. The suppressed address does not yet work with labeling. By contrast, sending to @example.com or @test.com returns 422 Unprocessable Entity because those domains are not designed for email traffic and produce bounces that damage sender reputation.
An invalid key produces a different error code on GET /emails/{id} than on another endpoint. That distinction affects application behavior, particularly retry logic keyed to a particular status code. To model the lifecycle, the simulator needs to keep records and match the details of the responses it returns when those records are accessed.
How can you test stateful Resend workflows locally without hitting production?
A stateful Resend simulator replaces the live API endpoint with a sandbox that retains state locally. The integration uses a sandbox bearer token instead of a live token, and no real email is sent or quota consumed. POST /emails returns a sandbox email ID and stores the message, allowing GET /emails/{id} to retrieve the record the application actually created.
That continuity also supports request replay and event handling. The simulator remembers idempotency keys, so repeating the same request returns the original response for the existing send. Lifecycle events fire on state changes and can be replayed against the existing sandbox state. These include email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.opened, email.clicked, email.failed, email.scheduled, email.suppressed, and email.received. Audience and contact mutations persist across calls as well.
Bounces are rare in normal traffic and difficult to trigger on demand against the live API, leaving their handlers systematically undertested. In the simulator, a test can fire email.bounced against an existing email and then replay it.
The application must distinguish hard from soft bounces, decrement a delivery score for repeated soft bounces from the same address, and suppress future sends to addresses that cross the hard-bounce threshold. It must also survive receiving the same bounce twice. These application behaviors require verification in the simulator. Persistent sandbox state provides the conditions in which their effects can be inspected.
Running Resend integration tests in CI without live credentials
For CI, the setup begins by creating a sandbox through the API at the start of the run. Set its bearer token as RESEND_API_KEY in the test environment, with no other application-code change in this pattern. Run the integration suite against the sandbox with isolated state for each test, keeping data separate across runs. Tear down the sandbox when the run ends. The lifecycle of the test environment is therefore explicit.
Production API keys have no place in that environment. Dedicated test keys still introduce quota consumption, rate limits, and the possibility of real delivery if the integration is misconfigured. Resend’s designated test addresses do not remove the quota cost. Resend states that test emails count against the account’s sending quota, which separates provider-backed testing from a simulator that sends nothing.
To turn the suite into a pipeline gate, use a single CI step that runs all email workflow checks. The step exits 0 when they pass and 1 when they fail, stopping integration regressions before the build reaches staging. Its assertions should cover webhook signature verification, idempotency replay with the same key and response, hard and soft bounce handling, suppression enforcement, and complaint processing. A send assertion alone is not this gate.
Template content belongs in the same CI coverage. Assert that the rendered output contains the correct from, to, subject, and key body content. Content correctness and lifecycle correctness test different obligations.
Fault injection: testing the error paths that only appear under pressure
A simulator that models only successful transitions leaves retry and recovery behavior untested. Email workflows also encounter rate limits, transient 503 responses, delayed webhooks, and duplicate events. Each fault interrupts a particular stage of the lifecycle. Testing those interruptions requires control over when they occur.
To exercise the send path, inject 429 Too Many Requests and check retry logic and backoff behavior. Inject a 503 to verify that the application handles the failure internally and degrades gracefully for the user. Artificial latency exposes timeout handling and async queue behavior.
After a bounce, duplicate delivery tests a different obligation. Replay the same event twice against the same state and verify that both deliveries are handled but exactly one suppression record results. The second delivery should be a no-op. This is the payoff of preserving the email and recipient state through the test, since the assertion depends on the first event’s effect being present when the second arrives.
Retry logic written for one invalid-key status code can fail on GET /emails/{id} because that endpoint returns a different one. Exposing that mismatch requires a simulator that preserves both responses, making resilience testing a question of fidelity as well as fault coverage.
Fidelity drift: why a simulator that isn't continuously verified becomes a liability
A provider schema change can leave an unmaintained simulator accepting behavior that the real API no longer accepts. The suite still passes just when it needs to warn of a broken integration. That creates false confidence. Persistent state improves the scope of testing, but it does not establish that the simulated contract still matches the provider.
The invalid-key inconsistency illustrates how even a small simplification can distort that contract. Normalizing the endpoints to one error code removes a real distinction that application retry logic encounters. Fidelity includes inconvenient behavior as well as documented success paths. A more uniform simulation is not necessarily a more accurate one.
OpenAPI-derived environments have a further boundary because they validate integration patterns against a known schema. They cannot replicate provider-specific business logic that lives outside it, including edge cases in delivery scoring, suppression list behavior, or infrastructure-level idempotency enforcement. Testing how the application responds to suppression does not prove that the provider behaves the same way.
Teams should test fidelity continuously against the live API. This verification work is distinct from running ordinary CI suites without live credentials. A simulator verified at release is a snapshot. Its continued usefulness depends on maintaining correspondence with the API as that API changes.
Where the Resend simulator fits into agent and RL workflows
An AI agent that uses Resend as an email tool must handle the same lifecycle as an integration written by a human. It can also extract parameters incorrectly, select the wrong endpoint, or produce coherent language while submitting malformed JSON. Fluent output does not establish a correct API operation. Agent evaluation therefore needs to check the request and what it does, including the state left after delivery events.
Live API testing is poorly suited to training or evaluation scale because quota consumption, rate limits, and real email delivery make runs expensive and non-repeatable. A stateful simulator separates agent behavior from that external variability. Deterministic responses make pass or fail attributable to the agent. Controllable bounce and complaint events then test whether the agent updates its internal model of recipient health correctly.
Isolation supports parallel evaluation as well as repeatability. The simulator runs in a container without external dependencies, so thousands of evaluation runs can take place without sharing state or competing for quota. Each run can keep the history it needs for a workflow in which the order of calls matters. Parallelism therefore need not sacrifice the continuity that makes lifecycle testing meaningful.
After processing a bounce and taking a suppression action, the agent receives the same event again. The test asks whether it recognizes that no second suppression action is required. For an agent as for application code, the resulting state provides the evidence.


