Idempotency keys and retries for transactional email APIs
Which API errors to retry and which to stop on, backoff with jitter in Python, and how to make sure a retry never sends the same receipt twice.
A transactional send fails sometimes: the API rate-limits you, a server has a bad minute, or the connection drops before you read the response. The safe pattern has three parts. Retry only errors that can succeed later, wait longer between each try with some randomness, and tie every message to an ID from your own system so a retry can never send the same password reset or receipt twice. This guide shows each part with code.
What a send call returns
With EmailMarketer.io, a transactional email is one authenticated POST to /api/v1/email. Each sending domain has its own API keys.
curl -X POST https://app.emailmarketer.io/api/v1/email \
-H "Authorization: Bearer $EM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"From": {"name": "Acme", "email": "no-reply@acme.com"},
"To": [{"email": "jane@example.com"}],
"Subject": "Your receipt",
"ContentType": "html",
"HTMLContent": "<p>Thanks for your payment.</p>",
"Tags": ["receipt"]
}'
A success returns a message ID:
{"MessageID": "6f1c2a9e-0b7d-4c1e-9a52-3f8e1d2c4b70"}
Store that ID. Webhooks and the event log use it, so it is how you later learn whether the message was delivered or bounced.
An error returns a list of codes and messages:
{"Errors": [{"Code": 14, "Message": "..."}]}
Which errors to retry
The rule: retry when the same request could succeed a little later. Stop when it will fail the same way every time.
| Response | Meaning | Retry? |
|---|---|---|
401 | The API key is missing or wrong | No. Fix the key |
403 | The key is not allowed to make this request | No. Check the key belongs to the sending domain |
409 | The recipient is suppressed (error code 14) | No. Mark the address in your app |
422 | The request failed validation | No. Fix the payload and log it |
429 | Too many requests | Yes, after a wait |
502 and other 5xx | A server or gateway problem | Yes, with backoff |
| Timeout or dropped connection | You don’t know if it was sent | Yes, but read the section on duplicates first |
A 409 deserves attention. A suppressed address has bounced hard, complained or unsubscribed. Retrying it will never work, and sending to it would hurt your reputation. Record it against the user so your app can ask them for a new address. Our post on email bounce codes covers what each kind of bounce means.
The HTTP standard says a 429 response may carry a Retry-After header with the number of seconds to wait (RFC 6585, RFC 9110). When a response includes it, wait at least that long. When it doesn’t, use your backoff.
Exponential backoff with jitter
Exponential backoff doubles the wait after each failed try. Jitter picks a random wait between zero and that limit, so a thousand workers that failed at the same moment don’t all retry at the same moment too.
With a base of 1 second, a cap of 30 seconds and 5 retries, the upper limit for each wait is:
| Retry | Upper limit (1 s × 2^(retry − 1)) | Actual wait |
|---|---|---|
| 1 | 1 s | random, 0 to 1 s |
| 2 | 2 s | random, 0 to 2 s |
| 3 | 4 s | random, 0 to 4 s |
| 4 | 8 s | random, 0 to 8 s |
| 5 | 16 s | random, 0 to 16 s |
The worst case is 1 + 2 + 4 + 8 + 16 = 31 seconds of waiting before you give up and hand the message to a slower queue. For a password reset, that is about as long as a user will wait.
import random
import time
import requests
API_URL = "https://app.emailmarketer.io/api/v1/email"
RETRY_STATUS = {429, 500, 502, 503, 504}
class PermanentError(Exception):
pass
def send_with_retry(payload, api_key, max_retries=5, base=1.0, cap=30.0):
headers = {"Authorization": f"Bearer {api_key}"}
for attempt in range(max_retries + 1):
try:
r = requests.post(API_URL, json=payload, headers=headers, timeout=10)
except (requests.Timeout, requests.ConnectionError):
r = None # outcome unknown, see the section on duplicates
if r is not None and r.ok:
return r.json()["MessageID"]
if r is not None and r.status_code not in RETRY_STATUS:
raise PermanentError(f"{r.status_code}: {r.text}")
if attempt == max_retries:
break
wait = random.uniform(0, min(cap, base * 2 ** attempt))
if r is not None and r.headers.get("Retry-After", "").isdigit():
wait = max(wait, int(r.headers["Retry-After"]))
time.sleep(wait)
raise TimeoutError("gave up after retries, requeue the message")
This sends a single recipient per call, which keeps one message ID per request and makes the bookkeeping below simple.
Why retries can send duplicates
Timeouts are the hard case. Your client gave up waiting, but the request may have reached the server and the email may be on its way. If you retry, the user can get two receipts.
The HTTP standard calls a request idempotent when repeating it has the same effect as sending it once (RFC 9110, section 9.2.2). PUT and DELETE are idempotent by design. POST, which sends the email, is not. Each successful POST is a new message.
Some APIs accept an idempotency key: a value you send with the request, and the server returns the first result when it sees the same key again. That helps, but it only covers the API’s window, and it does not help when your own code runs the same job twice. Build the protection into your system so it works the same with any email provider.
A retry is only safe when your system can tell that this exact message was already sent.
Idempotency keys from your own event IDs
Generate the key from the event that caused the email, never from a random value created at send time. A random key changes on every retry, so it protects nothing.
| Key built from | |
|---|---|
| Password reset | password-reset:{reset_token_id} |
| Receipt | receipt:{payment_id} |
| Invitation | invite:{invitation_id} |
| Daily digest | digest:{user_id}:{date} |
The key is stable: the same payment always produces receipt:pay_8812. Two workers, a retry, or a replayed job all compute the same key.
Send the same key with the request. The EmailMarketer.io send endpoint, POST /api/v1/email, accepts it as the IdempotencyKey field in the request body: 1 to 128 letters, digits, ., :, _ or -. A repeat with the same key from the same account and sending domain within 24 hours sends nothing and returns the first MessageID. A repeat while the first send is still running gets 409, so wait and try again. The send email docs list the details. The outbox below still matters, because a job that runs again a day later is outside that window.
Store before you send
Keep an outbox table. Insert the row before calling the API, with a unique constraint on the key. The database then refuses a second row for the same event.
CREATE TABLE email_outbox (
idem_key TEXT PRIMARY KEY,
recipient TEXT NOT NULL,
status TEXT NOT NULL DEFAULT 'pending',
message_id TEXT,
attempts INTEGER NOT NULL DEFAULT 0,
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
)
The flow for each message:
- Insert the row with
status = 'pending'. If the insert fails on the key, the email exists already. Stop. - Call the API with the retry function.
- On success, set
status = 'sent'and store theMessageID. - On a permanent error, set
status = 'failed'and keep the error. - If retries run out, the row stays
pending. A separate job checks oldpendingrows and decides whether to resend, using the rule in the warning below.
def send_once(db, idem_key, payload, api_key):
inserted = db.execute(
"INSERT INTO email_outbox (idem_key, recipient) VALUES (?, ?) "
"ON CONFLICT (idem_key) DO NOTHING",
(idem_key, payload["To"][0]["email"]),
).rowcount
if not inserted:
return # already sent or in progress
payload["Tags"] = payload.get("Tags", []) + [idem_key]
try:
message_id = send_with_retry(payload, api_key)
db.execute(
"UPDATE email_outbox SET status = 'sent', message_id = ? WHERE idem_key = ?",
(message_id, idem_key),
)
except PermanentError:
db.execute(
"UPDATE email_outbox SET status = 'failed' WHERE idem_key = ?", (idem_key,)
)
raise
Adding the key as a tag means the message carries your own ID along with it.
Send from a queue, not from the request
Do not call the email API inside the web request that the user is waiting on. Put the job on a queue and let a worker send it.
- The user’s page doesn’t hang while you back off.
- A small, fixed number of workers keeps you under the API’s request limit.
- A job that fails stays in the queue and runs again later, and the outbox table stops it from sending twice.
Most job queues (Sidekiq, Celery, BullMQ and others) have retries built in. Use their backoff settings, and keep the outbox check in the job itself.
Webhooks for delivery state
A MessageID means the API accepted the message. It does not mean the email reached the inbox. Webhooks tell you what happened next.
EmailMarketer.io sends webhooks for delivery, bounce, open, click and unsubscribe events. You set one URL per event for each sending domain, and every payload is signed with HMAC-SHA256. A failed webhook call is not retried, so keep your endpoint up and check the event log in the app when it was down.
In your webhook handler:
- Verify the signature before you trust the payload.
- Find the outbox row by
MessageIDand update its status: delivered, bounced, unsubscribed. - On a hard bounce, flag the address in your app.
- Return a
2xxquickly and do slow work on a queue. - Make the handler idempotent too. If the same event arrives twice, the second update should change nothing.
Checklist
- Retry
429,5xxand timeouts. Stop on401,403,409and422. - Use exponential backoff with full jitter and a cap. Honour
Retry-Afterwhen present. - Build an idempotency key from your own event ID, never from a random value.
- Insert into an outbox table with a unique key before you call the API.
- Store the
MessageIDfrom every success. - Send from a queue with a fixed number of workers.
- Track delivery and bounces with signed webhooks.
- Send transactional mail from its own subdomain. See keep transactional and marketing email apart.
Transactional email in EmailMarketer.io works over the API or SMTP and shares the plan’s monthly allowance with your campaigns. See transactional email for the details.