How it works
Send Idempotency-Key with POST /emails or POST /emails/batch: up to 256 printable ASCII characters, no spaces. Make it name the thing being sent, like order-1042-receipt, so a retry from anywhere in your code uses the same key.
- The same key and the same request within 24 hours answers what the first one answered — the same id, or ids for a batch — and queues nothing more. Nothing more counts against your caps.
- The same key with a different request within 24 hours is refused with
409andvalidation_error: use a new key for a new email. - After 24 hours the key is free, and a request with it is a new email.
- Keys belong to your account: another account’s keys never clash with yours.
- Keys for single sends and keys for batches are kept apart: a batch’s key covers the whole batch, in its order.
What counts as the same request
We compare the email as we read it, not its bytes: the order of the JSON’s fields, a lone address or a list of one, and a time written in another zone for the same moment are all the same request. A changed recipient, subject, body, header, tag or scheduled_at is a different one.
A refused request is not remembered: fix it and send it again with the same key.