Skip to main content
Network timeouts and client retries can send the same request more than once. Idempotency-Key lets Sendmux return the first result instead of running the operation again.

​
How it works

1

Send a stable key

Add Idempotency-Key to the original mutating request. Use a value that identifies the logical action, such as an order or invoice ID.
2

Retry with the same body

If the same key and body arrive again within 24 hours, Sendmux returns the original response.
3

Handle conflicts

If the same key arrives with a different body, or while the first request is still running, Sendmux returns 409 idempotency_conflict.

​
Example

curl -X POST https://smtp.sendmux.ai/api/v1/emails/send \
  -H "Authorization: Bearer smx_mbx_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmation-12345" \
  -d '{
    "from": { "email": "hello@example.com" },
    "to": { "email": "user@example.com" },
    "subject": "Order confirmation #12345",
    "html_body": "<p>Your order has been confirmed.</p>"
  }'

​
Where it applies

Use the header on mutating endpoints such as sending email, creating domains, creating mailboxes, suspending or resuming mailboxes, creating mailbox keys, creating sending accounts, activating or deactivating sending accounts, requesting sending-account limit increases, creating webhooks, rotating webhook secrets, and sending webhook test events. GET endpoints do not need it. Update and delete requests use their documented concurrency controls instead.

​
Key rules

  • Keep keys between 1 and 255 characters.
  • Reuse the same key for retries of the same operation.
  • Do not generate a new random key for each retry.
  • Do not put idempotency keys in the JSON body.
  • Treat 409 idempotency_conflict on an in-flight request as retryable after a short wait.

Send by HTTP

Use idempotency with single and batch sends.

API errors

Handle idempotency_conflict responses.