Idempotency
Send an Idempotency-Key on every request, so a retry never sends an email twice.
A network failure after we accepted your email but before your server read
the answer makes your code retry — and the customer gets two receipts. An
Idempotency-Key header prevents it. Send one on every request.
POST /v1/emails
Idempotency-Key: password-reset/7f1c2aHow it works
| You send | You get |
|---|---|
| A new key | The email is accepted as usual. |
| The same key and the same body, again | The first answer again, the same ids. No second email, no second charge. |
| The same key and a different body | 409 idempotency_conflict. Nothing is sent. |
| The same key while the first request is still running | 409 idempotency_in_flight. Wait the Retry-After seconds and retry. |
| The same key after the first request was refused | Checked again from the start, as a new request. |
| An empty key, one over 256 characters, or one with anything but printable ASCII | 400 invalid_idempotency_key. Nothing is sent. |
- A key is 1–256 printable ASCII characters: no line breaks, tabs, or Kurdish and Arabic letters.
- "Same body" means the same JSON values: key order and spacing don't matter; any changed value does.
- Only accepted requests are remembered. A refused request — no balance, over a cap, a domain not verified — leaves the key free, so you can fix the cause and retry with the same key.
- Keys are kept 24 hours from the first request, then the same key is new again. They are per workspace: two workspaces never collide.
- One key covers a whole batch.
POST /v1/emailsandPOST /v1/emails/batchshare keys, so reusing a key on the other endpoint is a conflict. idempotency_in_flightonly happens while a request with attachments or a large body is uploading; any other copy waits for the first and gets its answer.
Choosing a key
Build the key from the event that causes the email, not the moment you
send it — a random key made inside your retry loop is new every time and
protects nothing. A format that works everywhere:
<event-type>/<entity-id>.
| A good key | |
|---|---|
| Welcome email | welcome-user/123 |
| Order confirmation | order-confirmation/4821 |
| Password reset | password-reset/<reset token id> |
| Sign-in code | signin-code/<code id> |
| Monthly invoice | invoice/<customer id>/2026-11 |
From a job queue, the job's id is a good key — a retried job keeps its id.
Retrying safely
With a key on every request, this policy is safe:
| Answer | Retry? |
|---|---|
| Network error or timeout | Yes, with the same key. |
500 internal_error | Yes, with backoff. |
429 rate_limit_exceeded, 429 daily_limit_reached, 503 sending_unavailable | Yes, after the Retry-After header's seconds. |
409 idempotency_in_flight | Yes, after the Retry-After header's seconds. |
402 insufficient_balance | No. Add credits first, then send again — the same key works. |
Any other 4xx | No. The request itself is wrong; fix it. |
// Node / TypeScript: a send with retries that can never duplicate.
async function sendEmail(email: object, idempotencyKey: string) {
for (let attempt = 1; ; attempt++) {
let response: Response | undefined
try {
response = await fetch("https://api.charchy.krd/v1/emails", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CHARCHY_SEND_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(email),
})
} catch {
// network error: retry below
}
if (response?.ok) return response.json() // { id, status }
const code = response ? (await response.json()).error?.code : "network_error"
const retryable =
!response ||
response.status >= 500 ||
response.status === 429 ||
code === "idempotency_in_flight"
if (!retryable || attempt === 5) throw new Error(`Charchy Send: ${code}`)
const retryAfter = Number(response?.headers.get("retry-after")) || 2 ** attempt
await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000))
}
}