Idempotency

Network calls fail halfway. Idempotency lets you retry a write without risking a duplicate send.

How it works

Send an Idempotency-Key header (any unique string ≤ 256 chars — a UUID is ideal) on any creating request:

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 original response is replayed. The email is sent once, no matter how many times you retry.
• Same key + different body → 409 with error.code = "invalid_idempotent_request".
• Same key while the first is still in flight → 409 with error.code = "concurrent_idempotent_requests".

When to use it

Send a fresh key on every logical operation, and reuse that same key on retries of that operation. Keys are scoped to your organization and remembered for 24 hours.