Networks fail. If your request times out, you cannot tell whether the email was sent. Retrying could send it twice. The Idempotency-Key header solves this.
How it works
Send a unique key with each email you want sent exactly once:
POST /api/v2/emails
Idempotency-Key: order-1042-confirmation
- The first request with that key sends the email and returns its
id. - A retry with the same key and the same body within 24 hours returns the same
idand sends nothing. - A request with the same key but a different body fails with
409 invalid_idempotent_request, so a mistake cannot hide behind an old key.
Keys are up to 256 characters and are scoped to your account: two API keys of the same account share them.
Choosing keys
Use something that identifies the email in your system, such as order-1042-confirmation, password-reset-<token id> or a UUID you store with the job. Do not reuse a key for a different email.
Batches
On POST /api/v2/emails/batch, each email is remembered by its position in the array, so retrying the whole batch with the same key returns the same IDs. See Send batch.