Idempotency

Networks fail. If a send request times out, you can't tell whether usend received it. An idempotency key lets you retry without risking a duplicate email.

#Send an idempotency key

Add an Idempotency-Key header to POST /emails or POST /emails/batch. Use a value that identifies the message in your system, for example welcome-user-123 or order-1042-receipt. Keys can be up to 256 characters.

curl -X POST https://api.usend.et/emails \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your receipt",
    "text": "Thanks for your order."
  }'

await usend.emails.send(
  {
    from: 'Acme <[email protected]>',
    to: ['[email protected]'],
    subject: 'Your receipt',
    text: 'Thanks for your order.',
  },
  { idempotencyKey: 'order-1042-receipt' },
);

usend.emails.send(
    {
        "from": "Acme <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Your receipt",
        "text": "Thanks for your order.",
    },
    idempotency_key="order-1042-receipt",
)

#How it works

• Keys are scoped to your organization.
• The first request with a key sends the email. Repeating the request with the same key returns 200 with the same email ID, and nothing is sent again.
• For POST /emails/batch, a repeated key returns the exact response of the first batch request for 24 hours. Keys for single emails and for batches are separate.
• For POST /emails, the replay works for 24 hours, and after that for as long as the original email exists, because the key is stored with the email.
• usend does not compare request bodies: a repeated key returns the original result even if the body changed. Use a new key for a new email.
• If a request with the same key is still being processed, the second one fails with 409 concurrent_idempotent_requests. Wait and retry.
• If the first request fails (for example with 422), the key is released and you can retry with the same key after fixing the request.

#Errors