druidfi / mautic-bounce-webhook-bundle

1.0 2026-08-28 07:32 UTC

Requires

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

GPL-3.0-only

• Druid

• plugin
• email
• bounce
• webhook
• Mailjet
• Mautic

Published on Packagist.org on 2026-08-28 08:00 UTC

README

A Mautic plugin that handles mailer transport webhook callbacks for bounce and spam events. It processes incoming webhook payloads from email providers and automatically marks contacts as Do Not Contact (DNC) in Mautic.

Supported Providers

• Mailjet — processes bounce, blocked, and spam events via the Mailjet Event API

Requirements

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

Installation

Run the following command in your Mautic root directory:

composer require druidfi/mautic-bounce-webhook-bundle

Then clear the cache and go to the Plugins page in Mautic to install or upgrade the plugin.

Configuration

Set the following environment variables in your Mautic .env or server environment:

Variable	Required	Description
MAILER_BOUNCE_PROVIDER	Yes	The active bounce provider. Currently supported: mailjet
MAILER_CALLBACK_SECRET	No	A secret token to authenticate incoming webhook requests. If not set, all requests are accepted (not recommended for production).

Example:

MAILER_BOUNCE_PROVIDER=mailjet
MAILER_CALLBACK_SECRET=your-secret-token

Webhook URL

Configure your email provider to POST webhook events to:

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

Bounce Behaviour

Event	Provider behaviour	Mautic action
Hard bounce	bounce with hard_bounce: true	Contact added to DNC (Bounced)
Soft bounce	bounce with hard_bounce: false	Ignored
Blocked	blocked	Contact added to DNC (Bounced)
Spam complaint	spam	Contact added to DNC (Unsubscribed)

Adding a New Provider

1. Create a class implementing BounceProviderInterface
2. Add it as a constructor argument in BounceProviderRegistry
3. Register it in the $providers array with a matching key
4. Set MAILER_BOUNCE_PROVIDER to the new key

License

GPL-3.0-only