Idempotency and retries

Send Idempotency-Key with direct API requests. It is optional, but omitting it makes every accepted request a new email. SDKs generate a key for each new prepared request unless you supply one.

Keys accept 1–128 characters: letters, numbers, _, ., :, and -. Use a value such as welcome-123, and reuse it only with the original recipient, template, variables, and locale.

send() makes one attempt. Call prepare(...).retry(3).send() to allow up to three additional attempts. Calling retry() without a count also allows three retries; the supported range is 0–5. The example below uses the JavaScript SDK.

const email = sendery.prepare({
  to: '[email protected]',
  template: 'welcome',
  data: { name: 'Alex', action_url: 'https://example.com/start' },
}, 'welcome-123');

const receipt = await email.retry(3).send();

With retry() enabled, the SDK retries connection errors, unreadable responses, 500, 502, 503, 504, and 429 rate_limited. It waits between attempts and honors Retry-After. If that delay exceeds 30 seconds, it throws the error so you can try later. It does not retry validation, billing, capacity, or idempotency errors.

prepare() captures the data and key for that email. Reuse that object for another attempt. If your application restarts or recreates the request, supply the saved key and unchanged payload. A changed payload with the same key returns 409.

A matching retry returns 200 with the original message ID and its current status. It does not send a failed email again. An intentional resend needs a new key. Keys are scoped to a project and remain valid while the message record exists.