Email Webhooks: Syncing Bounces and Unsubscribes to Your CRM

Email webhooks push bounce and unsubscribe events to an endpoint you control. Your CRM can then update the contact and stop emailing it the moment the event happens. Without them? The CRM keeps mailing people who already bounced or opted out in the email platform. That hurts your sender reputation, and it ignores consent the contact has already taken back. Below: which events to use, how to build the endpoint, how to map events to CRM fields, how to deal with retries and duplicates, and how to test the sync before it goes anywhere near production data.

What email webhooks send and which events matter for your CRM

A webhook is an HTTP POST the email platform fires at your URL whenever something happens. No polling the API for changes. MailCraft sends four kinds of email event notifications: opens, clicks, bounces and unsubscribes. Both the webhooks and the REST API and webhooks come with the Pro plan. For CRM hygiene, bounces and unsubscribes are the ones that count, because they change what you’re allowed to send. Opens and clicks? Engagement signals. Nice to have, nothing more.

• Bounces: update the email status and, for permanent failures, block further sends.
• Unsubscribes: set a marketing opt-out flag and record when and where it happened.
• Opens: drop an activity on the timeline or feed it into a lead score.
• Clicks: log which link the contact clicked, for scoring or a sales follow-up.

How to set up a bounce webhook endpoint

You want one HTTPS endpoint that accepts the POST, validates it, stores the raw payload and sends back a 2xx fast. In my experience this order holds up well:

1. Put the endpoint on a stable, publicly reachable HTTPS URL.
2. Register that URL in the email platform and pick the events you want.
3. Save the raw request body before you parse or transform anything.
4. Respond with 200 as soon as the payload is stored.
5. Run the CRM updates in a background job that reads from storage.

Why the rush to acknowledge? Slow handlers hit timeouts, and then the platform redelivers events you may have already processed. So you end up doing the same work twice (or worse, doing it in the wrong order). If you haven’t talked to the platform programmatically before, start with your first API request. Get comfortable with authentication and payload formats first, then wire up webhooks.

Hard vs soft bounces: what should the CRM do with each?

A hard bounce is a permanent delivery failure, and the contact should be marked undeliverable. A soft bounce is temporary. Count it, and that’s it. The first digit of the enhanced status code tells you which one you’ve got: the standard for enhanced mail system status codes uses 5.x.x for permanent failures and 4.x.x for transient ones. Map each bounce to these CRM fields:

• Email status: valid, soft-bouncing or undeliverable.
• Bounce type: hard or soft, read from the status code.
• Last bounce date: the event timestamp, not the moment you processed it.
• Do-not-email flag: hard bounces only.

Don’t flag a contact after one soft bounce. Full mailboxes and busy servers usually sort themselves out. Block the address only after repeated failures. Where exactly to draw that line is up to you, and the rules for interpreting a bounce report will help you pick a sensible threshold.

Unsubscribe webhook CRM sync without losing consent history

An unsubscribe event sets a marketing opt-out flag on the matching CRM contact. It never deletes the record. Never. Match contacts on a normalized email address, which just means lowercased and trimmed of whitespace. And decide up front what happens when several CRM records share one address. Usually they all get the flag, because the person opted out, not one particular record. Store the timestamp and source of every opt-out, so you can prove the consent history later if someone asks. Then fold opt-outs and hard bounces into a single list the CRM checks before any send. The guide on keeping a suppression list shows how to structure it.

Handling webhook retries and duplicates with idempotency

Webhooks are delivered at least once. So your handler has to end up in the same state whether an event shows up once or three times. That’s idempotency. In practice: store a unique key for each event and skip any key you’ve already seen. If the payload has an event ID, use it. If not, build a key from the email, the event type and the timestamp.

Ordering is the other trap. Events can arrive out of order, so compare timestamps and never let an older event overwrite a newer state. A late bounce, say, shouldn’t undo a re-confirmation that happened after it. Return a non-2xx status only when you actually want the platform to redeliver. Log every failure, and set an alert for when the same error keeps coming back.

How to test and monitor the sync

Test with real events from a dedicated test list before the webhook ever touches production CRM data. Go through this checklist:

• Send to an address you know is invalid and confirm the hard bounce lands in the CRM.
• Unsubscribe a test contact and check that the opt-out flag, timestamp and source are all set.
• Replay the same payload twice and confirm the CRM fields change only once.

Once it’s live, compare received and processed events every day, and alert whenever the endpoint returns errors. Also reconcile the CRM against the platform’s suppression data on a regular schedule. Retries alone won’t bring back what got lost during an outage. Reconciliation will.

If you want one practical first step: subscribe only to bounces and unsubscribes, make the handler idempotent, and add opens and clicks once suppression works. Built in that order, email webhooks keep your CRM in line with your email platform, and nobody gets mail they’ve already refused or can’t receive.

FAQ