To retry an Emailer API send safely within its documented replay contract, keep the original Idempotency-Key and identical payload when acceptance is uncertain. Persist the source event ID and returned authorization ID too. Changing the key or content turns a recovery attempt into a different request and can obscure what was already accepted.
Persist three different identifiers
The business event, permission to send and request retry identity have different jobs. Store them with the application record before you need to diagnose a timeout. Do not create a new source-event identifier merely because your worker restarted.
| Identifier | Purpose |
|---|---|
| Source event ID | Identifies the real customer action being verified. |
| Authorization ID | Binds a permitted send to its recipient and exact content. |
| Send Idempotency-Key | Lets an identical admission request be replayed within the supported window. |
Keep verification retries separate from send retries
Retrying event verification with the same source ID and identical content returns the existing authorization while it remains valid. Changed content returns a conflict. This does not make stale events fresh or extend every authorization indefinitely.
Email admission has a documented 24-hour replay window for the same key and payload. One authorization cannot create multiple messages, including when different keys or concurrent requests are used. These checks are useful safeguards; they are not a claim of exactly-once delivery across the internet.
Make the response determine your next step
Example: your backend loses its connection while awaiting a send response. It cannot tell from that timeout alone whether the server accepted the message. Recover with the original persisted key and payload, then reconcile the returned identifier and later outcome.
| Observed result | Recovery approach |
|---|---|
| Timeout or lost response | Acceptance is uncertain. Keep the original key and identical payload. |
| 202 accepted | Track the existing message instead of creating a replacement. |
| 409 conflict | Inspect the conflict and stored request. Do not silently change identity. |
| 429 quota exhausted | Check the actual account allowance and reset boundary; do not loop blindly. |
| 503 capacity unavailable before acceptance | Inspect current capacity and event validity before a later attempt. |
Respect event validity and quota semantics
A later attempt still needs valid evidence and applicable account approval. Schedules must fit within event and approval expiry. When availability returns, recheck the original event and message state instead of altering timestamps or identifiers to force admission.
Recipient reservations count at acceptance, including messages that later fail or are canceled. Cancellation does not restore the reservation or make an event reusable. The documented pre-acceptance capacity rejection does not spend quota; distinguish it from an accepted request whose later attempt fails.
Own retry behavior in the application
The Node and Python SDKs do not automatically retry mutations or follow redirects. Your application therefore needs explicit recovery decisions, persisted identifiers and a way to inspect the result. Keep retry handling on the server, where the protected credentials and real event record belong.
Validation is a separate operation: pass the exact approved payload and omit Idempotency-Key. It checks current eligibility without sending or reserving quota. A previous validation success does not eliminate the need to handle a later timeout or changed service state.
Once the replay window has expired, do not assume the old key still provides replay protection. Reconcile the original message and source event through the available records before deciding on any new customer action. This guide explains the contract; test your application’s recovery behavior against the current documentation before relying on it.
Common questions
Can I retry using a fresh key if I never received the response?
Do not replace the key after uncertain acceptance. Preserve the original request identity and reconcile its result.
Does canceling let me send the same event again?
No. Cancellation does not refund the reservation or make the event reusable. Any later email must satisfy the actual event and sending contract.
Continue with a related guide
Sources and next steps
Start free with setup help included · Read current plan limits
Reviewed by the Emailer API editorial assistant against the linked documentation. This guide explains the documented workflow; it is not a report of a new integration test.