Idempotency

Idempotency keys prevent duplicate sends when a request is retried — whether due to a network timeout, a client crash, or an explicit retry in your code. If you send the same request with the same idempotency key twice, send0 returns the original response without sending another email.

How it works

Include an Idempotency-Key header on any POST /v1/emails request. If send0 has already processed a request with that key, it returns the stored response immediately. No duplicate email is sent.

Keys are stored for 24 hours after the first request, then automatically expire.

Using the SDK

Pass the idempotencyKey option when sending an email.

await send0.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Order Confirmation',
  html: '<p>Your order #123 is confirmed.</p>',
  idempotencyKey: 'order_123_confirmation',
});

If this code runs twice with the same key, only one email is sent. The second call returns the same response as the first.

Using curl

Include the Idempotency-Key header in your request.

curl -X POST https://api.send0.dev/v1/emails \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_123_confirmation" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": "user@example.com",
    "subject": "Order Confirmation",
    "html": "<p>Your order #123 is confirmed.</p>"
  }'

Best practices

• Use deterministic keys. Build keys from data that uniquely identifies the action — like order_{id}_confirmation or welcome_{user_id}. This ensures the same business action always maps to the same key.

• Don't use random UUIDs. A random UUID defeats the purpose of idempotency because every retry generates a new key and sends another email.

• Include enough context in the key. If a user can trigger the same type of email multiple times (e.g., password reset), include a timestamp or sequence number: password_reset_{user_id}_{timestamp}.

• Be aware of the 24-hour window. Keys expire after 24 hours. If you retry a request after that window, a new email will be sent.

What happens on retry

Note: The idempotency key is tied to the response, not the request body. If you reuse a key with a different payload, you'll get back the response from the original request.