Idempotency key
A caller-supplied key that makes retrying a send safe, so a network timeout cannot produce two emails
An idempotency key is a string you attach to a request so that retrying it cannot repeat its effect. The first request wins; a retry carrying the same key gets the original result back instead of doing the work again.
It exists because of one specific, common failure: your request reaches the server, the server sends the email, and the response is lost on the way back. Your code sees a timeout and cannot tell that from the request never arriving. Without a key, the safe-looking choice — retry — mails the customer twice.
How to choose one
Derive it from the thing the message is about, not from the moment of sending. An order
id, an invoice id, a password-reset-<user>-<token> — something that is stable across
retries because it identifies the same logical message.
A random value per attempt is worse than none: it looks like a safeguard and prevents nothing.
In Sendly
Pass Idempotency-Key on a send. Keys are 1 to 255 characters and are remembered for 24
hours.
A retry carrying the same key and the same body replays the original receipt. Reusing a
key with a different body answers 422 rather than serving another request's result —
which is the right outcome, because that combination means a bug rather than a retry.
The header works on the native send and through the Plunk compat endpoint. See the send API.