tvalimaa / mautic-bounce-webhook-bundle

1.0 2026-08-27 09:30 UTC

Requires

• php: ^8.1
• ext-json: *
• mautic/core-lib: ^5.0|^6.0|^7.0

GPL-3.0-only

• Tuomas Välimaa

• plugin
• spam
• bounce
• sendgrid
• mailgun
• webhook
• Mailjet
• Mautic
• dnc

Published on Packagist.org on 2026-08-27 09:35 UTC

README

An unofficial Mautic plugin that processes mailer transport webhook callbacks for bounce and spam events, automatically adding contacts to the Do Not Contact (DNC) list.

Supports Mailjet, SendGrid, and Mailgun out of the box. Adding new providers requires only implementing a single interface.

How it works

1. Your mailer sends a webhook POST to Mautic's transport callback endpoint.
2. The bundle selects the correct provider based on the MAILER_BOUNCE_PROVIDER env var.
3. The provider fingerprints the payload to confirm it matches the expected format.
4. Bounce, spam, and unsubscribe events are recorded via Mautic's TransportCallback, which marks the contact as DNC.

Hard bounces and permanent failures add contacts with DoNotContact::BOUNCED. Spam complaints and unsubscribes use DoNotContact::UNSUBSCRIBED. Soft bounces are logged and skipped.

Requirements

• Mautic 5, 6, or 7
• PHP 8.1 or higher

Installation

Copy or clone the bundle into your Mautic plugins/ directory:

cd /path/to/mautic/plugins
git clone https://github.com/tvalimaa/MauticBounceWebhookBundle.git

Then clear the Mautic cache and reload the plugins:

php bin/console cache:clear
php bin/console mautic:plugins:reload

Configuration

Set the following environment variables (e.g. in .env.local):

Variable	Required	Description
MAILER_BOUNCE_PROVIDER	Yes	Active provider: mailjet, sendgrid, or mailgun
MAILER_CALLBACK_SECRET	No	Secret token appended as ?token= to the webhook URL. When unset the endpoint is unrestricted (useful for local dev).

Example

MAILER_BOUNCE_PROVIDER=mailjet
MAILER_CALLBACK_SECRET=your-random-secret

Webhook URL

Configure your mailer to POST events to:

https://your-mautic.example.com/mailer/callback?token=your-random-secret

Supported providers

Mailjet

Handles bounce (hard only), blocked, and spam events from the Mailjet Event API.

SendGrid

Handles bounce (hard only), spamreport, unsubscribe, and group_unsubscribe events from the SendGrid Event Webhook.

Mailgun

Handles failed (permanent only), complained, and unsubscribed events from the Mailgun Webhook API v3.

Adding a custom provider

1. Create a class implementing BounceProviderInterface in the Provider/ directory.
2. Add it as a constructor argument in BounceProviderRegistry.
3. Register it with a key in $this->providers.
4. Set MAILER_BOUNCE_PROVIDER to the new key.

License

GPL-3.0-only