One key per logical send
Before a send, create a stable idempotency value for that business operation. Send it in the `Idempotency-Key` header. Reuse it only when retrying identical content for that same operation; use a new value for a genuinely new message.
When the result is uncertain
- Do not immediately submit the same message under a new key.
- Retry with the same idempotency value and byte-equivalent logical request content.
- If the server has already recorded the request, it returns the stored outcome instead of sending again.
- If the fingerprint differs, correct the client; changed content must use a new logical operation key.
Header requirements
The header is required, trimmed, and limited to 256 characters. Treat it as non-secret operational metadata, but avoid placing personal data in it. A suitable value can be an order or job ID that is unique for the sending account.
Provider boundary
Idempotency prevents duplicate sends through Mail’s durable send workflow. It cannot control what happens after an external mail system accepts a message. Treat `202` as provider acceptance, then use status and provider events for later delivery state.