Idempotency
Make retries safe with an idempotency key, so a timeout on a send that actually succeeded never mails the same person twice.
Updated
Networks fail after the work is done. Your request reaches us, we send the email, and the response is lost on the way back. Your code sees a timeout and retries - and the customer gets two one-time passcodes.
An idempotency key prevents that.
How to use it
Send an Idempotency-Key header with any request you might retry:
curl -X POST https://api.sendpository.com/v1/emails \
-H "Authorization: Bearer $SENDPOSITORY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10428-receipt" \
-d '{ "from": "...", "to": ["..."], "subject": "...", "html": "..." }'Replaying the same key on the same account returns the original message id instead of sending again:
{ "id": "d67e39ed-96be-4b35-ab22-853163d92c92" }Same response, no second email.
Choosing a key
Derive it from the thing that caused the email, not from the clock:
// Good - stable across retries of the same event.
`welcome-${user.id}`
`receipt-${order.id}`
`otp-${user.id}-${session.id}`
// Bad - different on every retry, so it protects nothing.
`otp-${Date.now()}`
crypto.randomUUID()A random key defeats the purpose
If the key changes between attempts, each attempt is a new message. The key must be the same on the retry as it was on the original.
Scope
Keys are scoped to your account, so they never collide with another customer's. They have no expiry - reusing one months later still returns the original id.
Where it matters most
One-time passcodes, password resets and payment receipts. Anything where a duplicate is confusing, alarming, or a security problem.