Mailgun Integration
Automatically sync unsubscribes, bounces, and spam complaints from Mailgun to your suppression lists.
On this page
Overview
The Mailgun integration uses webhooks to automatically add email addresses to your suppression lists when recipients unsubscribe, report spam, or experience permanent bounces.
Real-Time Sync
Events processed within seconds
Signed Webhooks
HMAC signature verification
Auto-Suppress
Configurable event handling
Prerequisites
- A Mailgun account with webhook access
- A List Armor campaign with at least one suppression list
- Your Mailgun domain verified and active
Setup in List Armor
- Navigate to your campaign and click ESP Integrations
- Click Add Integration and select Mailgun
- Choose the Target Suppression List where opt-outs will be added
-
Configure which events to auto-suppress:
- Hard bounces (recommended)
- Spam complaints (recommended)
- Unsubscribes (recommended)
- Add your Mailgun Webhook Signing Key for signature verification
- Save the integration and copy the Webhook URL
Important: Find your webhook signing key in Mailgun under Settings → Webhooks → Webhook Signing Key.
Configure Mailgun
- Log in to your Mailgun dashboard
- Select your sending domain
- Navigate to Sending → Webhooks
-
For each event type, click Add Webhook and paste your List Armor webhook URL:
- Permanent Failure — Hard bounces
- Complained — Spam complaints
- Unsubscribed — Unsubscribes
- Save each webhook configuration
Note: Mailgun requires you to set up each event type as a separate webhook, all pointing to the same List Armor URL.
Supported Events
| Mailgun Event | List Armor Action | Default |
|---|---|---|
permanent_fail
|
Add to suppression list | Enabled |
temporary_fail
|
Logged only (not suppressed) | N/A |
complained
|
Add to suppression list | Enabled |
unsubscribed
|
Add to suppression list | Enabled |
Testing
After configuring the webhooks, verify they're working:
- In Mailgun, use the Test Webhook button for each event type
- Check your List Armor integration for the Last webhook received timestamp
- Send a real test email and trigger an unsubscribe
- Verify the email appears in your target suppression list
Troubleshooting
- Verify webhooks are configured for each event type
- Check that the webhook URLs are correct
- Review Mailgun's webhook logs for delivery failures
- Ensure your domain is verified and active
- Verify you're using the Webhook Signing Key (not your API key)
- Re-copy the signing key from Mailgun Settings
- Check for extra whitespace when pasting
- Mailgun requires separate webhook setup for each event type
- Verify all three webhooks are configured (bounces, complaints, unsubscribes)
- Check that each webhook URL is saved correctly