Skip to content
Skip to main content

Idempotent send requests

Email

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

Section titled “Added”

  • Idempotency-Key header on send endpoints — Both POST /v3/grants/{grant_id}/messages/send and the Beta POST /v3/domains/{domain_name}/messages/send 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 — 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.