# Idempotent send requests

Source: https://developer.nylas.com/docs/changelogs/2026-04-28-idempotent-send/

Nylas's send endpoints now accept an `Idempotency-Key` header, so you can retry a send without delivering the same message twice. Generate a unique key per logical send (a UUID v4 works well), and Nylas caches the response — success or error — for 1 hour. This is the cornerstone for any send pipeline that retries automatically: workflow engines, background queues that redeliver on worker crash, or client code that retries after a network failure.

## Added

- **`Idempotency-Key` header on send endpoints** — Both [`POST /v3/grants/{grant_id}/messages/send`](/docs/reference/api/messages/send-message/) and the Beta [`POST /v3/domains/{domain_name}/messages/send`](/docs/reference/api/transactional-send/send-transactional-email/) accept the header. Keys are up to 256 characters and valid for 1 hour. Grant-based send is scoped per grant; transactional send is scoped per Nylas application (so the same key collides across all verified domains in an application).

- **Cached-response detection** — When a retry hits the cache, Nylas returns the original response body and status code with the `Idempotent-Response: true` header set. The first request through a key never has this header, so you can tell whether the provider was actually contacted on this request.

- **New error responses** — `400 api.invalid_idempotency_key` for keys longer than 256 characters; `409 api.invalid_idempotent_request` when a key is reused with a different request payload; `409 api.concurrent_idempotent_request` when a request with the same key is already in flight. Error bodies follow the standard Nylas error shape.

- **[Idempotent send requests guide](/docs/v3/email/idempotent-send/)** — Full coverage of key requirements, TTL, scoping rules, the retry decision matrix (when to reuse the same key vs. generate a new one), and the limitation that idempotency is enforced at the Nylas layer only — keys are not propagated to downstream providers.