Idempotency-Key lets you retry
safely: within a 24-hour window the API replays the original response instead of
running the operation again.
Send the header on any mutating request (POST, PATCH, DELETE). If you retry
with the same key, you get the original response back:
Idempotency is opt-in. A request with no
Idempotency-Key header behaves
normally - nothing is cached and every call runs. Reads (GET) are already
idempotent and ignore the header.How it works
- Generate a unique key per operation - a UUID is ideal. Use one key for one logical write, and reuse it only when retrying that same write.
- Keys are scoped to your workspace - a key you use never collides with another workspace’s, and the scope is derived server-side from your API key.
- Only successful (
2xx) responses are cached. If the first attempt failed, retrying with the same key genuinely re-runs the operation.
Exception - creating an API key is not idempotent. Its response contains a
one-time token that is never stored in retrievable form, so it cannot be replayed.
An
Idempotency-Key on POST /v1/api-keys is ignored, and a retry mints a new
key - delete any extras (list them first).Edge cases
Email sends never run unprotected. Other writes go through even if duplicate
protection is briefly unavailable - a stray duplicate draft is easy to clean up.
An email cannot be unsent, so
POST /v1/emails/{id}/reply, /forward and
POST /v1/campaigns/{id}/test-email sent with an Idempotency-Key refuse with
503 instead. The retry is safe.422 from a body mismatch looks like this: