Developed with love by KnpLabs Hire us for your project!


by azine

Symfony Bundle to easily capture feedback from via their provided webhooks


Symfony2 Bundle to capture event data from the transactional mail service.

If you are using a free account (less than 10'000 email per month), then deletes log-entries about events after about 48 hours.

So if you want to check who recieved the newsletter you sent last week, your busted. :-( offeres the cool feature to post the event data to an URL of your choice.
=> see for more details.

This bundle captures this data. You can search for, filter and display log-entries and
delete them when you don't need them anymore (or when you need to save some disk-space).


  • capture all data that can post via the "webhooks" provided by =>
  • display lists of event entries with search and filter functionality
  • show all details of a singel event
  • cli command to delete events 'old' events
  • cli command to check if mailguns sending ip address is on any block-list, including email notification to administrator if the IP is on a black-list.
  • email notification to administrator when mails bounce because of a SPAM rating


To install AzineMailgunWebhooksBundle with Composer just add the following to your composer.json file:

// composer.json
    // ...
    require: {
        // ...
        "azine/mailgunwebhooks-bundle": "dev-master",

Then, you can install the new dependencies by running Composer’s update command from
the directory where your composer.json file is located:

php composer.phar update

Now, Composer will automatically download all required files, and install them for you.
All that is left to do is to update your AppKernel.php file, and register the new bundle:


// in AppKernel::registerBundles()
$bundles = array(
    // ...
    new Azine\MailgunWebhooksBundle\AzineMailgunWebhooksBundle(),
    // ...

Register the routes of the AzineMailgunWebhooksBundle:

// in app/config/routing.yml

# Route for to post the information that we want to store in the database
    resource: "@AzineMailgunWebhooksBundle/Resources/config/routing/mailgunevent_webhook.yml"
    prefix:   /

# Routes for administration of the posted data
    resource: "@AzineMailgunWebhooksBundle/Resources/config/routing/mailgunevent_admin.yml"
    prefix:   /admin/

Configuration options

This is the complete list of configuration options with their defaults.
// app/config/config.yml

Default configuration for "AzineMailgunWebhooksBundle"


# Your api-key for mailgun => see
api_key:              ~ # Required

# Your public-api-key for mailgun => see
public_api_key:       ''


    # Whether to send notifications about spam complaints
    enabled:   false

    #Interval in minutes between sending of email notifications after receiving spam complaints
    interval:  '60'

    # Mailgun helpdesk ticket ID to request new IP address in case of spam complains
    ticket_id:      ''

    #Mailgun HelpDesk ticket subject
    ticket_subject: 'IP on spam-list, please fix.'

    #Mailgun HelpDesk ticket subject
    ticket_message: 'It looks like my ip is on a spam-list. Please, assign a clean IP to my domain."

    # Admin E-Mail to send notification about spam complaints
    alerts_recipient_email:     ''


    #Your public-api-key for hetrixtools => see
    api_key:        ''

    #Url for checking if ip is in blacklist => see
    blacklist_check_ip_url:    '<API_TOKEN>/blacklist-check/ipv4/<IP_ADDRESS>/'

# Sidenote on "monolog" emails and web scanners
You can configure monolog to send emails whenever an error occurs.

It is likely that many 404-errors occur on you site because web-scanners 
try to see if you are hosting vulnerable scripts on your server. If 
these errors are mailed via as well, you might send a lot more 
mails than you want to (and exceed the limit of 10k free emails) and it  
will clutter you database with more or less useless information.

Since Symfony 2.4, to avoid these emails being sent, you can configure 
monolog to ignore certain 404 errors.

// app/config/config.yml
type: fingers_crossed
action_level: warning
handler: yourNextHandler
- ".*/cgi-bin/php.*"
- ".*MyAdmin/scripts/setup.php.*"
- ".*autoconfig/mail/config-v1.1.xml.*"
- ".*vtigercrm/graph.php.*"
- ".*/HNAP1/.*"
- ".*calendar/install/index.php.*"
- ".*admin/config.php.*"

Webhooks configuration of

To tell to post the data to your database via the webhooks, just
get the full url of the "mailgunevent_webhook"-route

# on a bash console execute this to get the absolute webhook path
php bin/console debug:router -e prod | grep mailgunevent_webhook 
// note for Symfony 2.x it is 'php app/console debug:router -e prod | grep mailgunevent_webhook'

and copy it to all the input fields for the webhooks on

Then test if everything is setup ok by clicking the "Test" or "Send" button and check
you database or the event-list.

# on a bash console execute this to get the absolute overview-page path
php bin/console router:debug -e prod | grep mailgun_overview
// note for Symfony 2.x it is 'php app/console debug:router -e prod | grep mailgun_overview'


Whenever mailgun posts an event via the webhook, an MailgunWebhookEvent containing the
new MailgunEvent is dispatched.

You can implement your own means of notification for failures or if you configured your
application to use the swiftmailer, you can use the SwiftMailerMailgunWebhookEventListener,
to send emails to an address you specified.

Cli Commands

This bundle offers two commands for you to automate things via a scheduler (cronjob).

Delete old MailgunEvents

If you only want to keep mailgun events younger than date string, to prevent your database of running full, you can run the command via scheduler/cronjob.

# e.g. delete all events older than 60 days
php app/console mailgun:delete-events -date '60 days ago'

Check if Sending IP is on Black-Lists

If the IP address, your emails are sent from, gets listed on a SPAM block-list, your email deliverability drops drastically.
To be able to be notified a.s.a.p. you can run this command to check the last IP, that was used for sending your emails, against If the IP is listed, the administrator will receive an email.

# e.g. delete all events older than 60 days
php app/console mailgun:check-ip-in-blacklist -numberOfAttempts 5

With the parameter numberOfAttempts you can specify how many times the command should try to get the hetrixtools report, if an attempt fails for any reason. has a free, limited plan that will allow ~3 checks per day. See for details.


Contributions are very welcome. Please fork the repository and issue your pull-request against the master branch.

The PR should:
- contain a description what the PR solves or adds to the bundle (reference existing issues if applicable)
- contain clean code with some iniline documentation and phpdocs, no "pure whitespace" changes.
- respect the Symfony best practices and coding style
- have phpunit tests covering the new feature or fix
- result in a 'green' build for your branch on before you issue the PR

Code style

You can check the code style with the php-cs-fixer. Optionally you can set up a pre-commit hook which contains the php-cs-fixer check. Also see

All you have to do is to move pre-commit.sample file from commit-hooks/ to .git/hooks/ folder and rename it to pre-commit.

php-cs-fixer will check the style of your new added code each time you commit, showing you what you have to fix.


Here's a list of open TODOs
- write more unit-tests
- add commands to "cleanup" the database periodically
- add SwiftMailerMailgunWebhookEventListener to notify admins when certain events occur => email upon "dropped" event
- write some CSS, style pages

Build-Status ec.

Build Status
Total Downloads
Latest Stable Version
Scrutinizer Code Quality
Code Coverage

  • Merge branch 'testingDev1' of into merged-testingDev1
    By azine, 11 months ago
  • php_cs_fixer integration
    By azine, 11 months ago
  • speed up functional test
    By azine, 1 year ago
  • Fix tag param when tag is sent using X-Mailgun-Tag header over SMTP (#32)
    By azine, 1 year ago
  • php_cs_fixer integration
    By eugene-o-z, 1 year ago
  • fix tests, improve translations, add titles to cockpit-links
    By azine, 1 year ago
  • update documentation for cli commands
    By azine, 1 year ago
  • minor fixes (phpDoc, unused imports, variable naming)
    By azine, 1 year ago
  • remove unused constructor parameter, fix error-handling
    By azine, 1 year ago
  • fix unit-tests
    By azine, 1 year ago
  • fix unit-tests
    By azine, 1 year ago
  • rename functions, make "private" functions private, replace IPs & domains with example domain/IP
    By azine, 1 year ago
  • make commandline output more verbose
    By azine, 1 year ago
  • update translations, add IP address to email notification about blacklists
    By azine, 1 year ago
  • added/update phpDocs, removed unused function
    By azine, 1 year ago
  • testing of successful response
    By azine, 1 year ago
  • replacing of fake domain names
    By azine, 1 year ago
  • Handling error response from hetrixtools and implementing of retry functionality
    By azine, 1 year ago
  • tests for blacklist check functionality
    By azine, 1 year ago
  • Command for checking if ip is in blacklist
    By azine, 1 year ago
  • update .travis.yml
    By azine, 1 year ago
  • fix test
    By azine, 1 year ago
  • translations
    By azine, 1 year ago
  • fix translations
    By azine, 1 year ago
  • fix merge-error
    By azine, 1 year ago
  • Send notifiations to admins about spam complaints
    By web-flow, 1 year ago
  • make mailgun-cockpit-dashboard look a bit nicer
    By azine, 1 year ago
  • fix bug in finding last sender ip
    By azine, 1 year ago
  • refactor delete-events-command to be a service
    By azine, 1 year ago
  • run Tests on Symfony 3.4 (#20)
    By azine, 1 year ago