Send Mailgun events back to your suppression list

Point your Mailgun webhooks at your workspace. Permanent failures, complaints, and unsubscribes update your suppression list.

Get started free Delivery feedback

Fig. 1Mailgun → Verifier

1.1 Mailgun

MailgunWebhooks

1.2 Delivery endpoint

Token in the URL
Signature with your signing key
Timestamp window

1.3 Recorded as

delivered → deliveredHistory
failed (permanent) → bouncedSuppressed
complained → complainedSuppressed
unsubscribed → unsubscribedSuppressed
opened → openedHistory
clicked → clickedHistory

POST /v1/inbound/providers/mailgun/{endpoint}/{token}

Source: Mailgun webhooks
Verification: Signing key and timestamp
Suppressed: Bounces, complaints, unsubscribes
Setup: One private URL

§ 1

Why it matters

Delivery problems stay inside Mailgun

When an event is only recorded in the email platform, the address comes back with the next import.

Close the loop between Mailgun and your list checks.

Fig. 2Without and with Verifier

WithoutWith Verifier

Without: Permanent failures stay in the Mailgun logs.With Verifier: Each Mailgun event is checked with your signing key.
Without: Imports from other tools bring the same addresses back.With Verifier: Permanent failures, complaints, and unsubscribes join one list.
Without: Suppression lists differ from tool to tool.With Verifier: Every event shows in the address history.

§ 2

How it works

A private URL for each endpoint

Mailgun signs each webhook with your signing key. Verifier checks the signature and the timestamp before it records the event.

2.1In Mailgun, open Sending > Webhooks, and copy the HTTP webhook signing key.
2.2In Verifier, open Outcomes, and add a Mailgun endpoint with that key. Copy its private URL.
2.3In Mailgun, add the URL for the Permanent Failure, Spam Complaints, and Unsubscribes events.

Fig. 3One bounce from Mailgun

Sent by Mailgun

{  "signature": {    "timestamp": "1760605964",    "token": "a8ce0edb2dd8...",    "signature": "d2271d12299f..."  },  "event-data": {    "event": "failed",    "severity": "permanent",    "recipient": "[email protected]"  }}

Verifier · POST /v1/inbound/providers/mailgun/{endpoint}/{token}

{  "provider": "mailgun",  "accepted": 1,  "duplicates": 0,  "rejected": 0}

GET /v1/suppressions/[email protected]

{  "suppressed": true,  "reason": "bounce",  "source": "mailgun"}

Signed with your Mailgun signing key · fields trimmed

§ 3

What you get

What you get.

3.1One suppression listSuppressions from Mailgun sit next to invalid results and manual entries.
3.2Event historySee the delivery events for each address in its history.

Table 3 · Event mapping

Event from the platform	Recorded as
delivered	delivered
failed (permanent)	bounced
complained	complained
unsubscribed	unsubscribed
opened	opened
clicked	clicked

§ 4

In practice

Typical uses.

Case 4.1
Stop repeat problems
A suppressed address goes to the drop file when you clean your next list.
Case 4.2
More than one sending tool
A Mailgun bounce also stops the address in lists from your CRM and other tools.

Other integrations.

All integrations

Questions

Before you start.

Which events are recorded?

The event mapping on this page shows what is recorded. Permanent failures, complaints, and unsubscribes go on the suppression list.

Is a temporary failure suppressed?

No. Only a failure with severity permanent is recorded as a bounce. A temporary failure is not added to the suppression list.

Delivery problems stay inside Mailgun

When an event is only recorded in the email platform, the address comes back with the next import.

Close the loop between Mailgun and your list checks.

Fig. 2Without and with Verifier

WithoutWith Verifier

Without: Permanent failures stay in the Mailgun logs.With Verifier: Each Mailgun event is checked with your signing key.
Without: Imports from other tools bring the same addresses back.With Verifier: Permanent failures, complaints, and unsubscribes join one list.
Without: Suppression lists differ from tool to tool.With Verifier: Every event shows in the address history.

A private URL for each endpoint

Mailgun signs each webhook with your signing key. Verifier checks the signature and the timestamp before it records the event.

2.1In Mailgun, open Sending > Webhooks, and copy the HTTP webhook signing key.
2.2In Verifier, open Outcomes, and add a Mailgun endpoint with that key. Copy its private URL.
2.3In Mailgun, add the URL for the Permanent Failure, Spam Complaints, and Unsubscribes events.

Fig. 3One bounce from Mailgun

Sent by Mailgun

{  "signature": {    "timestamp": "1760605964",    "token": "a8ce0edb2dd8...",    "signature": "d2271d12299f..."  },  "event-data": {    "event": "failed",    "severity": "permanent",    "recipient": "[email protected]"  }}

Verifier · POST /v1/inbound/providers/mailgun/{endpoint}/{token}

{  "provider": "mailgun",  "accepted": 1,  "duplicates": 0,  "rejected": 0}

GET /v1/suppressions/[email protected]

{  "suppressed": true,  "reason": "bounce",  "source": "mailgun"}

Signed with your Mailgun signing key · fields trimmed

What you get.

3.1One suppression listSuppressions from Mailgun sit next to invalid results and manual entries.

3.2Event historySee the delivery events for each address in its history.

Table 3 · Event mapping

Event from the platform	Recorded as
delivered	delivered
failed (permanent)	bounced
complained	complained
unsubscribed	unsubscribed
opened	opened
clicked	clicked

From a raw listto a safe send.

Send Mailgun events back to your suppression list

Delivery problems stay inside Mailgun

A private URL for each endpoint

What you get.

Typical uses.

Other integrations.

Before you start.

From a raw listto a safe send.

Send Mailgun events back to your suppression list

Delivery problems stay inside Mailgun

A private URL for each endpoint

What you get.

Typical uses.

Other integrations.

Before you start.