A customer emails your support agent at 9:14 a.m. At 9:15 they get a helpful reply. At 9:16 they get the same reply again, word for word. Nothing crashed. No exception was thrown. Your agent just did exactly what it was told — twice.
I think email agents are the best teacher of idempotency I've seen in years, because the failure mode is so visceral. A duplicate database row is invisible. A duplicate email lands in a human's inbox and makes your product look broken. Building a reply loop on Nylas Agent Accounts (currently in beta) forced me to internalize lessons that apply to any event-driven system, not just email.
Lesson 1: at-least-once is the honest contract
The instinct is to blame the platform: "why did I get the same webhook twice?" But at-least-once delivery is the only honest guarantee a webhook system can make. Per the duplicate-reply docs, if your endpoint doesn't return 200 fast enough, or a transient network blip eats the response, the message.created notification gets delivered again. The alternative — exactly-once — would mean the platform silently drops events whenever it's unsure, and a dropped event is worse than a repeated one.
So duplicates aren't a bug to report. They're a contract to design for. The fix is an atomic check-and-set keyed on the message ID:
