Charchy Senddocs

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/7f1c2a

How it works

You sendYou get
A new keyThe email is accepted as usual.
The same key and the same body, againThe first answer again, the same ids. No second email, no second charge.
The same key and a different body409 idempotency_conflict. Nothing is sent.
The same key while the first request is still running409 idempotency_in_flight. Wait the Retry-After seconds and retry.
The same key after the first request was refusedChecked again from the start, as a new request.
An empty key, one over 256 characters, or one with anything but printable ASCII400 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/emails and POST /v1/emails/batch share keys, so reusing a key on the other endpoint is a conflict.
  • idempotency_in_flight only 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>.

EmailA good key
Welcome emailwelcome-user/123
Order confirmationorder-confirmation/4821
Password resetpassword-reset/<reset token id>
Sign-in codesignin-code/<code id>
Monthly invoiceinvoice/<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:

AnswerRetry?
Network error or timeoutYes, with the same key.
500 internal_errorYes, with backoff.
429 rate_limit_exceeded, 429 daily_limit_reached, 503 sending_unavailableYes, after the Retry-After header's seconds.
409 idempotency_in_flightYes, after the Retry-After header's seconds.
402 insufficient_balanceNo. Add credits first, then send again — the same key works.
Any other 4xxNo. 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))
  }
}

On this page