Idempotency

How it works

Network errors and timeouts leave you not knowing whether an email was accepted. Send an Idempotency-Key header with POST /api/v1/emails or POST /api/v1/emails/batch and retry with the same key: Bytesms accepts the email once and returns the original response to every retry.

# Send with an idempotency key
curl -X POST 'https://api.bytesms.com/api/v1/emails' \
  -H 'Authorization: Bearer tp_live_xxxxxxxxx' \
  -H 'Idempotency-Key: welcome-user-123' \
  -H 'Content-Type: application/json' \
  -d '{"from":"Acme <[email protected]>","to":["[email protected]"],"subject":"Welcome","html":"<p>Welcome aboard.</p>"}'

Rules

• A key is 1–256 characters; anything else is 422 invalid_idempotency_key.
• Keys are scoped to the workspace and remembered for 24 hours.
• Same key + same body → the stored response (for example the same { id }), no second email.
• Same key + a different body → 409 idempotency_key_conflict. Bodies are compared after sorting JSON keys, so key order doesn't matter.
• Two concurrent requests with the same key still create only one email.
• Single sends and batch sends keep separate key spaces.

{
  "statusCode": 409,
  "message": "This Idempotency-Key was already used with a different request body. Use a new key for a different email.",
  "name": "idempotency_key_conflict"
}