# Idempotency (/docs/api-reference/idempotency)

`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.

```bash
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](/docs/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](/docs/sdk/errors#automatic-retries) sends a key on every `POST` and reuses
it across its automatic retries.
