Idempotency

Networks fail mid-request. Your code retries. Without idempotency, your user gets two receipts. With it, the retry returns the original result.

How it works

Send Idempotency-Key: <unique-value> with POST /v1/emails. The first request stores its result durably, scoped to your project. Repeating the key within 24 hours returns the stored result with a 200 — no second email, no second charge, no second meter tick.

When to use it

Always, on every send. Generate UUIDs per logical operation (one per user action, not one per retry attempt), and for recurring jobs use dated keys like invoice-run-2026-09-06 so a retried cron replays instead of duplicating.

What it doesn’t do

Different keys are different operations — a new key always sends. And idempotency covers acceptance, not outcomes: if the email later bounces, that’s a delivery event, not a duplicate.