Idempotency

Retry POST requests without sending twice, using the Idempotency-Key header: for 24 hours, a repeat with the same key returns the original result.

POST /v1/emails accepts an Idempotency-Key header (1–256 characters). For 24 hours, a repeated request with the same key:

  • and the same body returns the email with its current status (including queued), with an Idempotent-Replayed: true header;
  • and a different body fails with 422 idempotency_key_reused;
  • concurrent matching requests wait for the first transaction to commit and replay its email. A busy key can return 409 request_in_progress with a Retry-After header.
curl -X POST https://api.coss.com/v1/emails \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user-123" \
  -d '{"from":"Acme <hello@acme.com>","to":"user@example.com","subject":"Welcome","text":"Hi!"}'

POST /v1/emails/batch works the same way, with one key for the whole batch: a replay returns the same batch, with each email's current status. Batch keys and single-send keys are separate, so the same key can be used once for each.

POST /v1/hooks/applications/{application}/messages (Hooks) works the same way: a replay returns the first message, and a reused key with another message body fails with 422 idempotency_key_reused. Its keys are separate from email keys.

Derive keys from your own data (welcome-${userId}) so that a retry after a crash reuses the same key. The TypeScript SDK sends a key on every POST and reuses it across its automatic retries.

Last updated