Sending

Idempotent requests

Retry a send after a timeout without any risk of sending it twice.

Networks fail. If a send times out, you can't tell whether Chebu received it. Add an Idempotency-Key header to POST /emails or POST /emails/batch, and retry with the same key. Chebu sends the email once and replays the first response for every retry.

Request

curl -X POST https://api.chebu.io/emails \
  -H "Authorization: Bearer $CHEBU_API_KEY" \
  -H "Idempotency-Key: welcome-email/user_8412" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Northwind <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Welcome to Northwind",
    "html": "<p>Glad you'\''re here.</p>"
  }'

How keys behave

Situation	Result
Same key, same body, within 24 hours	The original response, replayed. Nothing new is sent.
Same key, different body	`409 invalid_idempotent_request`
Same key while the first request is still running	`409 concurrent_idempotent_requests`. Retry shortly.
Key empty or over 256 characters	`400 invalid_idempotency_key`
Same key after 24 hours	Treated as a new request.

Choosing keys

Derive the key from the thing you're emailing about, such as receipt/order_1042 or welcome-email/user_8412, so every retry of the same job uses the same key.
Don't reuse a key for a different email. Chebu will reject it rather than guess.