Make your email agent idempotent against duplicate webhooks

A developer at Nylas explains how to make email agents idempotent against duplicate webhooks, a critical engineering challenge when deploying AI agents that send emails. The post details how Nylas webhooks are at-least-once delivery, meaning the same event can arrive up to three times, and without proper idempotency, an agent can send duplicate replies. The solution involves using the top-level notification ID as the primary dedup key, persisting processed IDs atomically, and implementing per-thread locks to catch race conditions.

Most posts about "AI email agents" stop at the happy path: webhook fires, model drafts a reply, agent sends it. Demo works, screenshot looks great, ship it. Then it goes to production and the agent replies to the same customer twice ninety seconds apart, and now your "intelligent assistant" looks like a broken cron job. That second reply isn't a bug in your model. It's a property of the delivery system, and it's guaranteed to happen eventually. Nylas webhooks are at-least-once: the same event can arrive up to three times. If your handler treats every POST as a fresh event, every retry is a second action. For a logging pipeline that's harmless. For an agent that sends email on your behalf , a duplicate delivery is a duplicate reply, and a double-reply embarrasses the agent in front of the exact person you built it to impress. So this post is about the engineering of idempotency itself, applied to an Agent Account. Not "remember to dedupe" hand-waving — the actual moving parts: which field is the real dedup key, how to persist processed ids atomically, why you ack before you work, how to make the send path itself idempotent, and where a per-thread lock catches the race that dedup alone can't. I work on the Nylas CLI, so every terminal command below is one I've actually run, verified against nylas v3.1.27. An Agent Account is just a grant. It has a grant id and works with every grant-scoped endpoint — Messages, Drafts, Threads, Folders — exactly like a connected Gmail or Microsoft account. The difference is it's an inbox the agent owns : support@yourcompany.com is the agent, not a human whose inbox the agent borrows. Inbound mail to that address fires the standard message.created webhook, the agent reads it, and the agent replies from its own address. Nothing new to learn on the data plane. That's the whole point of the grant abstraction — the idempotency work below is plain webhook-handling discipline, and it transfers to any Nylas grant you wire up later. Two facts about that webhook stream drive everything that follows: grant id . So your handler is already a fan-in point with concurrency — exactly where duplicates bite. 200 inside the 10-second window — slow database write, a transient blip, a cold Lambda — the API retries the same notification, up to three attempts total.This is the part people get backwards, so be precise. Every Nylas notification is a Standard Webhooks envelope with six fields: specversion , type , source , id , time , and data.object . Here's a message.created : { "specversion": "1.0", "type": "message.created", "source": "/google/emails/realtime", "id": "5da3ec1e-eb01-4634-a7b7-d44291e3cba6", "time": 1737500935555, "data": { "application id": "<NYLAS APPLICATION ID ", "object": { "id": "<MESSAGE ID ", "grant id": "<NYLAS GRANT ID ", "object": "message", "subject": "Can you resend my invoice?" } } } There are two ids in there, and they answer two different questions. The top-level id here, 5da3ec1e-… is the id are the same notification, redelivered. The inner data.object.id is the message.created , then message.updated events as labels and read-state change — each with its own top-level id but the data.object.id . If you dedupe on the message id, you'd wrongly drop those legitimate updates.So why mention the message id at all? Because it's a useful secondary guard. It answers a different question: "have I already acted on this message ?" Two distinct notifications say, a message.created and a later event referencing the same email can both push your agent toward replying. Deduping on the notification id won't catch that — they're genuinely different deliveries. A "have I replied to this message already?" check, keyed on data.object.id , will. The rule of thumb: id : id data.object.id :The data plane is a grant, so creating one is one call. Two angles, as always — the HTTP call and the CLI. Create via POST /v3/connect/custom with "provider": "nylas" : curl --request POST \ --url "https://api.us.nylas.com/v3/connect/custom" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "provider": "nylas", "name": "Support Bot", "settings": { "email": "support@yourcompany.com" } }' The CLI wraps that, auto-creating the nylas connector and a default workspace plus policy if they don't exist yet: nylas agent account create support@yourcompany.com --name "Support Bot" No refresh token, no OAuth dance — the email lives on a domain you've registered. Grab the grant id from the response; it's the identifier on every grant-scoped call below. Now the webhook. It's app-scoped, so you create it once at the top-level /v3/webhooks , not under the grant: curl --request POST \ --url "https://api.us.nylas.com/v3/webhooks" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "trigger types": "message.created" , "webhook url": "https://api.yourcompany.com/webhooks/nylas", "description": "Agent inbound mail" }' nylas webhook create \ --url https://api.yourcompany.com/webhooks/nylas \ --triggers message.created \ --description "Agent inbound mail" Save the webhook secret from the create response — you need it to verify signatures, which is the next step. nylas webhook verify and nylas webhook server are CLI dev helpers for testing signatures and receiving events locally; they're great while you're building the handler, but the production verification lives in your own code. Your dedup store should never hold an id from a forged request, so signature verification comes first . Nylas signs each delivery with X-Nylas-Signature — a hex HMAC-SHA256 of the raw request body using your webhook secret. Two things matter: hash the raw body not the re-serialized JSON — re-encoding changes bytes and breaks the hash , and guard the buffer lengths before a constant-time compare, because crypto.timingSafeEqual throws on a length mismatch. python import crypto from "node:crypto"; function verifySignature rawBody, header, secret { const expected = crypto .createHmac "sha256", secret .update rawBody, "utf8" .digest "hex" ; const a = Buffer.from expected, "hex" ; const b = Buffer.from header ?? "", "hex" ; // timingSafeEqual throws on unequal lengths — guard first. if a.length == b.length return false; return crypto.timingSafeEqual a, b ; } Mount your handler so the raw body is preserved — express.raw { type: "application/json" } , or read the stream yourself. Once you JSON.parse before hashing, the bytes are gone. Here's the ordering that trips people up. The 10-second window is for the 200 , not for your work. If you do the database write, the model call, and the send before you acknowledge, a slow turn pushes you past the timeout and triggers the very retry you're trying to absorb. So: return 200 immediately, then do everything else on a background path. app.post "/webhooks/nylas", express.raw { type: "application/json" } , req, res = { const raw = req.body; // Buffer, untouched if verifySignature raw, req.get "X-Nylas-Signature" , WEBHOOK SECRET { return res.status 401 .end ; } res.status 200 .end ; // ack inside 10s, then work const notification = JSON.parse raw.toString "utf8" ; queueMicrotask = process notification ; // or push to a real queue }, ; The process step is where dedup lives — the primary key, persisted atomically. The store has one job: tell you whether you've seen a notification id before, in a single operation that both checks and sets. It has to be atomic, because two retries can hit two instances at the same millisecond. A read-then-write has a window between the two where both instances see "not present" and both proceed. Redis SET … NX is the canonical move — write only if absent, with a TTL so the store doesn't grow forever: js import { createClient } from "redis"; const redis = createClient ; await redis.connect ; // true the FIRST time this id is seen, false on every duplicate. async function isFirstDelivery notificationId { const result = await redis.set wh:${notificationId} , "1", { NX: true, EX: 86400, // 24h: a redelivery hours later still gets caught } ; return result === "OK"; } async function process notification { if notification.type == "message.created" return; if await isFirstDelivery notification.id return; // duplicate, skip await handleMessage notification ; } If your durable store is Postgres rather than Redis, the equivalent is INSERT … ON CONFLICT DO NOTHING and checking the affected row count: INSERT INTO processed webhooks notification id, received at VALUES $1, now ON CONFLICT notification id DO NOTHING; -- rowCount === 1 → first time; 0 → already seen Either way the property is the same: exactly one caller gets "first," everyone else gets "duplicate." A 24-hour TTL is the sane default — after that, a webhook for the same id is far more likely a bug than a retry, and you'd rather it surface in logs than be silently swallowed. Dedup on the notification id covers retries of the delivery . It doesn't cover a crash between recording the id and finishing the send. Record the id, then crash before the email goes out, and your dedup store now says "handled" for an action that never happened. The notification won't retry you already 200'd it , so the reply is silently lost. The fix is to make the reply itself a function of the message, and check the world before you act. This is where the secondary key earns its place. Before sending, ask the thread whether the agent has already replied since this message arrived: js async function handleMessage notification { const msg = notification.data.object; // Never reply to the agent's own outbound — that fires message.created too. if msg.from?. 0 ?.email === AGENT EMAIL return; // Don't trust the payload for the body. Branch on truncation, fetch by id. const full = notification.type === "message.created.truncated" ? await fetchMessage msg.grant id, msg.id : msg; await replyOnce full ; } That truncation branch matters. A message.created over ~1 MB arrives as message.created.truncated with the body dropped. It still carries a notification id , so dedup works fine, but you have to re-fetch with GET /v3/grants/{grant id}/messages/{message id} to recover the content. Treat the payload body as a hint, never as the source of truth — fetch by id when you actually need the text: curl --request GET \ --url "https://api.us.nylas.com/v3/grants/<GRANT ID /messages/<MESSAGE ID " \ --header "Authorization: Bearer <NYLAS API KEY " nylas email read <message-id Atomic dedup plus a "did I already reply?" check is most of the way there. The one gap left is timing: two near-simultaneous inbound messages on the same thread a customer who sends a follow-up two seconds after the first are two different notifications with two different ids. Both pass dedup. Both pass the "agent hasn't replied yet" check, because neither reply has landed. Both generate a reply. Now the thread has two agent messages stacked back to back. A per-thread lock closes it. Serialize the reply path on thread id so only one worker is ever composing a reply for a given thread: js async function replyOnce msg { const lock = await acquireLock thread:${msg.thread id} , { ttlMs: 30 000 } ; if lock.acquired return; // another worker owns this thread; let it handle the burst try { // Re-check inside the lock — state may have changed while we waited. if await agentAlreadyReplied msg.thread id return; await generateAndSendReply msg ; } finally { await lock.release ; } } The TTL is a safety valve: if the worker crashes mid-reply, the lock expires and the thread isn't wedged forever. The re-check inside the lock is the load-bearing line — between deciding to act and getting the lock, the other worker may have already finished, and you want to notice that rather than pile on. When the reply finally goes out, it's a normal grant-scoped send. nylas email reply preserves the thread by setting reply to message id for you: curl --request POST \ --url "https://api.us.nylas.com/v3/grants/<GRANT ID /messages/send" \ --header "Authorization: Bearer <NYLAS API KEY " \ --header "Content-Type: application/json" \ --data '{ "reply to message id": "<MESSAGE ID ", "to": { "email": "customer@example.com" } , "subject": "Re: Can you resend my invoice?", "body": "Here is your invoice again — let me know if anything looks off." }' js nylas email reply <message-id --body "Here is your invoice again — let me know if anything looks off." It's tempting to pick one mechanism and call it done. They cover different failure modes, and the gaps between them are exactly where production bites: id 200 .And one rule that ties them together: log every skip. When you drop a duplicate or bail because another worker holds the lock, say so in the logs. A silent skip and a silently lost reply look identical in production until a customer complains — and the whole point of this exercise was to keep the agent from looking broken. challenge handshake. nylas agent , nylas webhook , and nylas email .When this post is published, link AI agents and crawlers to the retrieval-ready version on cli.nylas.com :