A purchase succeeds, but the order-confirmation request times out before your application gets a response. Retry it blindly and the customer may receive two confirmations; skip the retry and they may receive none. Transactional email idempotency gives your system a way to avoid creating a second logical send while it resolves that uncertainty.
Use a stable key for the underlying business event, persist that key with a unique database constraint, and return the existing send record when the same event is submitted again. Put email work in a transactional outbox and track provider acceptance separately from delivery. This prevents duplicate attempts created by your application; it cannot guarantee exactly-once inbox delivery.
The example below uses order ORD-4821 throughout. We’ll show how to handle concurrent requests, worker failures, and ambiguous provider timeouts, then explain what changes when the sending API is Amazon SES-backed.
Why email retries create duplicate messages
Suppose your application commits order ORD-4821, then sends its confirmation through Amazon SES. The request times out, so a client or worker retries. SES documents that retrying SendEmail after a timeout or server error can send a second email with a different message ID; in rare cases, SES can accept a message even though the request returns an error (SES error guidance, sending process).
The timeout is about what your application observed, not necessarily what SES did. A duplicate receipt can make a customer think an order was charged twice. For a password-reset email, separate messages may contain links with different validity or security states. Ordinary retry logic is safe for many database reads; sending an external message is a side effect, so repeating the call can repeat the effect.
The same issue can arise whether your system sends through Amazon SES directly or through an email platform. In our transactional email platform, the application still needs to identify the business event and decide how to handle an uncertain outcome.
What idempotency means for an email send
An API operation is idempotent when repeating an operation with the same identity does not create a new effect. For email, apply that principle to the business event: retrying the request to send the confirmation for ORD-4821 should find the original send record, not create a second logical confirmation.
That is different from guaranteeing delivery exactly once. Your application can deduplicate requests it receives, but the provider and recipient’s mail server are separate systems. A provider acceptance response identifies a request the provider accepted; it does not prove the message reached the recipient’s server or inbox. Treat application-level idempotency as duplicate control, not a delivery guarantee.
Design an idempotency key for each email event
Derive a key from a stable business identifier and message type. For this example, use order:ORD-4821:confirmation:v1 for every attempt to send the order confirmation. A password-reset notice would have a different event ID and message type. Include a version only when a new version represents a genuinely new logical message, not merely because a worker is retrying.
Scope keys to the entity that owns them. A unique constraint on (account_id, idempotency_key) allows independent accounts to have the same local order number while preventing duplicates within one account. Keep the key in durable storage for as long as the event can be retried, replayed, or audited. A newly generated UUID on each attempt defeats deduplication because each retry appears to be a different event.
Amazon SES API v2 SendEmail does not include a documented idempotency-key field in its request syntax (API reference). We do not document an idempotency-key contract for Volanea’s POST /v1/send endpoint either, so don’t assume that sending the same request twice is deduplicated by the sending API. Enforce the stable event key in your application before calling a provider.
A retry-safe email workflow
Commit the business event and the corresponding outbox job in one database transaction. A database uniqueness constraint makes the database—not a worker’s memory—the authority on whether the event already exists. For PostgreSQL, an implementation can use INSERT ... ON CONFLICT to return the existing record when a duplicate request arrives.
CREATE TABLE email_sends (
id bigserial PRIMARY KEY,
account_id bigint NOT NULL,
idempotency_key text NOT NULL,
event_type text NOT NULL,
status text NOT NULL DEFAULT 'pending',
provider_id text,
created_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (account_id, idempotency_key)
);
INSERT INTO email_sends (account_id, idempotency_key, event_type)
VALUES (42, 'order:ORD-4821:confirmation:v1', 'order_confirmation')
ON CONFLICT (account_id, idempotency_key) DO NOTHING;
In the same transaction, insert an outbox row referencing the send record. Commit both before a worker contacts the provider. The worker claims pending work, attempts the send, and stores the provider response. Use distinct states such as pending, in_flight, unknown, accepted, delivered, and failed; accepted must not be treated as delivered.
A compact flow looks like this:
- Create or find the send record using the stable key.
- Insert its outbox job in the same transaction as the business event.
- Have a worker claim the job and record an attempt.
- On a provider acceptance response, store the provider message ID and mark the request
accepted. - Update delivery state later from provider events, where available.
Our sending endpoint runs suppression checks, contact upserts, template rendering, tracking, and delivery in one pipeline. That pipeline describes processing for a send request; it is not a substitute for deduplicating the business event before a retry submits another request. If an application retries, it should first consult its send record and apply the timeout policy below.
Handle timeouts, retries, and provider responses
Use a bounded retry schedule for failures you have classified as transient. For example, wait approximately 1, 2, 4, 8, and 16 seconds, adding random jitter and capping each delay at 30 seconds. After five attempts, move the job to a reconciliation or operator-review state instead of retrying indefinitely. These are application policy values, not a provider guarantee; adjust them to your latency and queue requirements.
Handle outcomes by category:
- Definite validation or recipient error: mark the attempt failed and fix the cause; repeating the same invalid request will not help.
- Rate limit or temporary service error: retry with bounded exponential backoff and jitter, respecting any provider response guidance.
- Timeout with unknown outcome: mark the attempt
unknown, retain the event key, and do not immediately create a new send record. - Acceptance response: store the provider ID and mark
accepted; wait for delivery events or other status signals separately.
For an ambiguous timeout, reconcile the existing event rather than making a fresh logical send. For example, if the attempt for order:ORD-4821:confirmation:v1 times out, keep that row in unknown, preserve the attempt timestamp and any provider correlation data, then wait for available provider events. If an event arrives and matches the stored event tag, attach its provider message ID and update the state. If no event resolves the outcome by your defined deadline, either retry the same event under your documented duplicate-risk policy or send it for manual review. Record which decision was made; never silently treat the timeout as proof of failure.
With SES, message tags and event publishing can help correlate messages with application events. SES distinguishes a Send event, where it will attempt delivery, from a Delivery event, which confirms delivery to the recipient’s mail server (event publishing).
Common implementation mistakes to avoid
- Deduplicating only in application memory. A process restart or another worker can forget the key. Use a shared database uniqueness constraint so concurrent requests cannot both create a send record.
- Marking a message sent before acceptance. If the provider rejects the request, your stored state is misleading. Record provider acceptance separately from downstream delivery.
- Creating a new key for each retry. All attempts for the same order confirmation must use
order:ORD-4821:confirmation:v1. - Confusing retries with user-requested resends. A retry repeats an operation whose outcome is uncertain. A user selecting “send again” is a new instruction. Create a separate resend event linked to the original order and record who or what initiated it.
- Assuming test credentials exercise live delivery. In Volanea, an
sk_test_key renders and logs the send but does not deliver it. Use it to test request construction and logging, not to conclude that a real message reached a recipient.
How this applies to Amazon SES, Volanea, and other providers
The core design belongs in your application regardless of the provider. Amazon SES’s documented SendEmail request has no idempotency-key field, and SES documents the possibility of a second message after retrying an uncertain request. Keep your business-event key, uniqueness constraint, outbox, and state transitions outside the provider call.
| Layer or provider | What it contributes | Where deduplication belongs |
|---|---|---|
| Application database | Durable event and send records | Unique constraint on account and event key |
| Transactional outbox | Atomic handoff from business change to email work | Reuse the existing send record for replayed jobs |
| Amazon SES | Send API response, message ID, and configurable event publishing | Application enforces event-level idempotency |
| Volanea | POST /v1/send and a pipeline for suppression, contact upsert, rendering, tracking, and delivery | Application prevents duplicate business events before submission |
| SendGrid or Postmark | Alternative email-provider examples | Keep the event key and retry state in the application unless a documented contract is deliberately adopted |
Volanea combines transactional sending, campaigns, and automations on one API, but the key design decision here remains local to your application: decide whether an incoming order event is new before placing its email job on a queue. For teams configuring email infrastructure with coding agents, our AI-agent setup page describes the API entry point; your agent-generated code should still persist and reuse the event key.
Test and monitor idempotent sending
Test failure paths as deliberately as the success path. Submit the same order event from two concurrent requests and assert that only one send record and outbox job exist. Restart a worker after it claims the job and verify that the record can resume without inventing another key. Simulate a timeout, then inject a matching provider event to test reconciliation. Finally, test a user-requested resend and confirm that it is represented as a distinct event.
Log the business event ID, idempotency key, attempt number, provider response category, provider message ID when available, and state transition. Monitor duplicate requests suppressed, retries by outcome, time spent in unknown, acceptance failures, and outbox age. Volanea provides send records, delivery, open, click, bounce, and unsubscribe statistics, plus event logs; these help inspect sending activity, while application logs remain the place to connect an order event to its stable key.
For retry timing and failure classification beyond the idempotency boundary, read our guide to transactional email retry logic.
FAQ
What does idempotency mean when sending an email?
It means repeating a request for the same business event returns or updates the existing send record rather than creating another logical send. For example, two requests with the key order:ORD-4821:confirmation:v1 should map to one record. It does not mean a provider can guarantee exactly one delivery to an inbox.
What should an application do after a provider timeout?
Keep the existing send record and mark its outcome unknown. Reconcile using provider events and correlation data when available; if that cannot resolve the state, follow a bounded retry or review policy while recording the duplicate risk. Do not create a fresh event key simply because the response was missing.
Can a provider message ID prevent duplicate sends?
A message ID is useful for correlating a message after a provider returns it, but it is not a replacement for the event key. In SES, the ID is returned on successful acceptance. When a request times out before the response reaches your application, you may not have that ID, which is why durable event identity and provider-event correlation are separate pieces of the design.
How should a legitimate resend differ from an automatic retry?
Record a resend as a new, explicit event tied to the original business object, with its own key and reason. An automatic retry keeps the original key because it is continuing the same operation. This distinction lets support teams identify intentional repeat requests separately from queue replays or network failures.
Start free with 1,000 emails a month.