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.

Technical drawing of a pneumatic dispatch machine with a cable socket, a stamping press marking a unique stub on each capsule, and a duplicate capsule diverted into a bin.

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.

ResponseMeaningRetry?
401The API key is missing or wrongNo. Fix the key
403The key is not allowed to make this requestNo. Check the key belongs to the sending domain
409The recipient is suppressed (error code 14)No. Mark the address in your app
422The request failed validationNo. Fix the payload and log it
429Too many requestsYes, after a wait
502 and other 5xxA server or gateway problemYes, with backoff
Timeout or dropped connectionYou don’t know if it was sentYes, 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:

RetryUpper limit (1 s × 2^(retry − 1))Actual wait
11 srandom, 0 to 1 s
22 srandom, 0 to 2 s
34 srandom, 0 to 4 s
48 srandom, 0 to 8 s
516 srandom, 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.

EmailKey built from
Password resetpassword-reset:{reset_token_id}
Receiptreceipt:{payment_id}
Invitationinvite:{invitation_id}
Daily digestdigest:{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:

  1. Insert the row with status = 'pending'. If the insert fails on the key, the email exists already. Stop.
  2. Call the API with the retry function.
  3. On success, set status = 'sent' and store the MessageID.
  4. On a permanent error, set status = 'failed' and keep the error.
  5. If retries run out, the row stays pending. A separate job checks old pending rows 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.

Technical drawing of a machine with an API socket and an SMTP chute feeding envelopes onto one conveyor line.
FIG. 01API and SMTP feed the same sending line. Either way, retries belong in your code before the message reaches it.

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:

  1. Verify the signature before you trust the payload.
  2. Find the outbox row by MessageID and update its status: delivered, bounced, unsubscribed.
  3. On a hard bounce, flag the address in your app.
  4. Return a 2xx quickly and do slow work on a queue.
  5. Make the handler idempotent too. If the same event arrives twice, the second update should change nothing.

Checklist

  1. Retry 429, 5xx and timeouts. Stop on 401, 403, 409 and 422.
  2. Use exponential backoff with full jitter and a cap. Honour Retry-After when present.
  3. Build an idempotency key from your own event ID, never from a random value.
  4. Insert into an outbox table with a unique key before you call the API.
  5. Store the MessageID from every success.
  6. Send from a queue with a fixed number of workers.
  7. Track delivery and bounces with signed webhooks.
  8. 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.

Get new posts by email

Guides on sending at volume, deliverability and pricing. One email when a post goes up. Unsubscribe any time.

By subscribing you agree to receive these emails. See the Privacy Policy.

Keep reading

Recommended posts

ProductNovember 10, 20265 min read

Run email reports from Claude or ChatGPT

Connect an AI assistant to EmailMarketer.io over MCP and use it for weekly reports, segment checks and pre-send audits, while people keep the final send.

LifecycleOctober 13, 20267 min read

Onboarding emails triggered by product events

Replace day-based drips with emails that follow what users do in your product. Pick the activation event, plan your events, send them from your app and measure.