[05]Sending
Idempotency
Send an Idempotency-Key header on any creating POST and a retry returns the original response instead of sending a second email. Keys are scoped per workspace and retained 24 hours. True exactly-once delivery does not exist across a network boundary, so here is what we do guarantee.
| Boundary | Guarantee |
|---|---|
| Accept | At-most-once per (workspace, idempotency key) |
| Provider | At-least-once, with duplicate suppression by provider message id |
| Campaigns | Effectively-once, enforced by the recipient primary key |
We document this honestly because a customer building billing emails needs the real guarantee, not a marketing claim. A replayed request returns the stored response with an Idempotent-Replay: true header. Reusing a key with a different body is an idempotency_conflict, not a silent overwrite.
POST /v1/emails
Idempotency-Key: order-1043-confirmation
# ... retried after a timeout ...
HTTP/1.1 202 Accepted
Idempotent-Replay: true
{ "id": "msg_01J8XQ7M2K9PQRSTUV", "status": "queued" }Pick a key from your own domain
The best idempotency key is something meaningful from your side — an order id plus the email type, not a random UUID generated at call time. A random key regenerated on retry defeats the whole mechanism.