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 anIdempotent-Replayed: trueheader; - 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_progresswith aRetry-Afterheader.
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