API reference

Idempotency

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 id and 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.