Idempotency
Retry supported email sends with an Idempotency-Key.
Network calls can fail halfway. Idempotency lets you retry a supported email send without a second API acceptance during the key's retention window.
How it works
Send an optional Idempotency-Key header (a unique string of at most 256
characters; a UUID is a good choice) on POST /v1/emails,
POST /v1/emails/batch, or POST /v1/emails/bulk:
curl https://api.sendmailos.com/v1/emails \
-H "Authorization: Bearer sk_live_your_key" \
-H "Idempotency-Key: 9f8b7c6d-..." \
-H "Content-Type: application/json" \
-d '{ "from": "...", "to": "...", "subject": "...", "html": "..." }'- Same key + same body → the accepted result is replayed, with a replay warning. No new send is enqueued by that retry.
- Same key + different body →
409witherror.code = "invalid_idempotent_request". - Same key while the first is still in flight →
409witherror.code = "concurrent_idempotent_requests".
When to use it
Send a fresh key on every logical operation, and reuse it only for retries of that operation. Keys are recorded for 24 hours; use a different key for each logical send, including sends through different endpoints. A key omitted from the request gives no replay protection. After the retention window, check the original email status before deciding to submit a new request; a network failure can leave the provider outcome uncertain.
This guarantee is implemented for the email send routes listed above. Do not assume that adding this header makes another mutating endpoint idempotent.