# 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.

```http
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.