Blog

How to handle email bounces and replies with webhooks

· SyncYak team

  • mail-api
  • webhooks
  • bounces

If your product sends email from your users' own Gmail or Outlook accounts, sending is the easy half. The hard half is what comes back: a reply that should update a record, a bounce that should stop the next follow-up, a message that arrives twice because your endpoint timed out. Polling each mailbox on a timer works for a demo and falls over at fifty mailboxes.

Webhooks fix that. The mail provider tells you when something happens, and your code reacts. This post covers the three things a webhook handler has to get right: verifying the sender, reacting to bounces, and matching replies to the conversation they belong to. The examples use the Nylas v3 format that SyncYak Mail speaks, so they apply to any API that follows it.

The events worth handling

You do not need every event on day one. Start with these:

  • message.created fires when a new message lands in a connected mailbox.
  • thread.replied fires when someone answers a thread you are tracking.
  • message.bounce_detected fires when a message you sent could not be delivered.
  • Open and click events fire when tracking is turned on for a send.

A typical message.created delivery is a small JSON document. It names the grant (the connected mailbox), the message id, the subject, the sender and a short snippet:

{
  "specversion": "1.0",
  "type": "message.created",
  "id": "5f0c...",
  "time": 1790000000,
  "data": {
    "grant_id": "b1e4...",
    "object": {
      "id": "18c2...",
      "subject": "Re: Your showing on Saturday",
      "from": [{ "email": "[email protected]", "name": "Sam" }],
      "snippet": "Saturday works. See you there."
    }
  }
}

Keep the handler thin. Verify, record the event, return 200, and do the real work in a queue. Mail providers retry slow endpoints, and a handler that does a CRM update inline will eventually time out and invite a duplicate.

Verify every delivery

Your webhook URL is public, so anyone who finds it can post to it. Each delivery carries an X-Nylas-Signature header: the hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. Compute it yourself and compare in constant time.

import crypto from 'node:crypto';

export function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Two mistakes show up again and again. The first is hashing the parsed JSON instead of the raw bytes: re-serializing changes whitespace and key order, and the signature no longer matches. Capture the raw body before your framework parses it. The second is skipping verification in development and forgetting to turn it on. Make the check unconditional and use a test secret locally.

Treat a bounce as a stop sign

A bounce is the one event where doing nothing causes damage. If you keep sending follow-ups to an address that does not exist, your user's own mailbox reputation pays for it, because the mail goes out from their address, not yours.

When message.bounce_detected arrives:

  1. Find the message you sent by its id and mark the recipient address as undeliverable on that contact.
  2. Cancel any queued follow-ups to that address.
  3. Show the sender a plain note in your app: "Mail to [email protected] bounced". Do not make them dig through a mailbox to learn it.
  4. Keep the record. A later correction to the address should be a deliberate edit, not a silent retry.

Hard and soft failures differ. A mailbox that does not exist is permanent. A full mailbox or a temporary server problem may clear up. Store the reason the event gives you and decide per case instead of treating every bounce as final.

Match replies to the right record

A reply is useful only if you can tie it to something. Matching on the sender's address alone breaks the moment a lead writes from a second address or two of your users email the same person.

Match on the thread instead. When you send through the API, store the id of the sent message against your own record (the lead, the order, the showing). When thread.replied or message.created arrives, look up the thread, find the record it belongs to, and act:

  • update the status of the lead to "replied";
  • stop any automated nurture sequence for that person;
  • notify the user who owns the mailbox.

Check the grant id as well. The same person can write to two of your users, and the grant tells you whose mailbox received the message. Use the pair of grant id and thread id as your key.

Make the handler safe to run twice

Webhooks are delivered at least once, so duplicates will happen. Use the event id as an idempotency key: insert it into a table with a unique constraint before doing any work, and return 200 straight away if the insert says it already exists. The same table gives you a log to read when someone asks why a follow-up did or did not go out.

A short checklist for the whole handler:

  • read the raw body and verify the signature;
  • insert the event id, and stop if it is already there;
  • enqueue the work and return 200 quickly;
  • handle bounces before replies, because a bounce can cancel work a reply would restart;
  • alert yourself when the handler fails repeatedly, so a broken endpoint does not go unnoticed for a week.

Test it without deploying

You do not need a deployed server to try any of this. Run the handler on your laptop, expose it with a local tunnel, and register the public URL as a webhook endpoint. Send a test message from a connected mailbox to a second address you control, reply to it, and watch the events arrive. A bad address such as a made-up domain gives you a real bounce to practice on. The tunnel safety checklist covers locking that temporary URL down.

How SyncYak helps

SyncYak Mail gives your users a hosted page to connect Gmail, Microsoft 365 or any IMAP mailbox, then sends on their behalf with one call to POST /v3/grants/{grant_id}/messages/send. New mail, replies, bounces, opens and clicks post to your endpoint, signed with HMAC-SHA256. Open and click tracking is available from the Hobby plan. If you already run against the Nylas v3 format, the request and webhook shapes are the same, so you change the API host, the client ID and the secret. The email webhooks page and the Mail docs show the events in full.

The Free plan connects 3 mailboxes and sends 1,000 messages a month, which is enough to wire up and test everything above. See pricing for the larger plans.

Ready to try it? Create a free account, connect one mailbox, and send yourself a message that bounces.

Start free with SyncYak · All posts