AzineMailgunWebhooksBundle
Symfony Bundle to capture event data from the Mailgun.com transactional mail service., (*1)
If you are using a free mailgun.com account (less than 10'000 email per month), then
mailgun.com deletes log-entries about events after about 48 hours., (*2)
So if you want to check who recieved the newsletter you sent last week, your busted. :-(, (*3)
Mailgun.com offeres the cool feature to post the event data to an URL of your choice.
=> see http://documentation.mailgun.com/user_manual.html#webhooks for more details., (*4)
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)., (*5)
Features
- capture all data that mailgun.com can post via the "webhooks" provided by mailgun.com => http://documentation.mailgun.com/user_manual.html#webhooks
- 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
Installation
To install AzineMailgunWebhooksBundle with Composer just add the following to your composer.json file:, (*6)
// 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:, (*7)
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:, (*8)
<?php
// in AppKernel::registerBundles()
$bundles = array(
// ...
new Azine\MailgunWebhooksBundle\AzineMailgunWebhooksBundle(),
// ...
);
Register the routes of the AzineMailgunWebhooksBundle:, (*9)
// in app/config/routing.yml
# Route for mailgun.com to post the information that we want to store in the database
azine_mailgun_webhooks_bundle_webhook:
resource: "@AzineMailgunWebhooksBundle/Resources/config/routing/mailgunevent_webhook.yml"
prefix: /
# Routes for administration of the posted data
azine_mailgun_webhooks_bundle_admin:
resource: "@AzineMailgunWebhooksBundle/Resources/config/routing/mailgunevent_admin.yml"
prefix: /admin/
Configuration options
This is the complete list of configuration options with their defaults., (*10)
// app/config/config.yml
# Default configuration for "AzineMailgunWebhooksBundle"
azine_mailgun_webhooks:
# Your api-key for mailgun => see https://mailgun.com/cp
api_key: ~ # Required
# Your public-api-key for mailgun => see https://mailgun.com/cp
public_api_key: ''
# Your domain as configured on mailgun.com
email_domain: ''
# in case you also use the AzineEmailBundle, you can configure what to link to the web-view
web_view_token: "azineemailwebviewtoken"
# reply-email-address for delivery-error-notifications
no_reply_email: "no-reply@mubuproperties.co.uk"
# reply-name for delivery-error-notifications
no_reply_name: "MuBu Properties Mailer"
spam_alerts:
# 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: ''
hetrixtools_service:
#Your public-api-key for hetrixtools => see https://hetrixtools.com/
api_key: ''
#Url for checking if ip is in blacklist => see https://docs.hetrixtools.com/blacklist-check-api/
blacklist_check_ip_url: 'https://api.hetrixtools.com/v2/<API_TOKEN>/blacklist-check/ipv4/<IP_ADDRESS>/'
#Number of days to mute spam-blacklist notifications if the blacklist didn't change
repeat_notification_after_days: 0
Sidenote on "monolog" emails and web scanners
You can configure monolog to send emails whenever an error occurs.
=> http://symfony.com/doc/current/cookbook/logging/monolog_email.html, (*11)
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 mailgun.com 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., (*12)
Since Symfony 2.4, to avoid these emails being sent, you can configure
monolog to ignore certain 404 errors.
=> http://symfony.com/doc/current/cookbook/logging/monolog_regex_based_excludes.html, (*13)
// app/config/config.yml
monolog:
handlers:
main:
type: fingers_crossed
action_level: warning
handler: yourNextHandler
excluded_404s:
- ".*/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 mailgun.com
To tell mailgun.com to post the data to your database via the webhooks, just
get the full url of the "mailgunevent_webhook"-route, (*14)
# 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 https://mailgun.com/app/webhooks, (*15)
Then test if everything is setup ok by clicking the "Test" or "Send" button and check
you database or the event-list., (*16)
# 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'
Events
Whenever mailgun posts an event via the webhook, an MailgunWebhookEvent containing the
new MailgunEvent is dispatched., (*17)
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., (*18)
Cli Commands
This bundle offers two commands for you to automate things via a scheduler (cronjob)., (*19)
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., (*20)
# 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
hetrixtools.com. If the IP is listed, the administrator will receive an email., (*21)
# e.g. check the blacklists, retry 5 times before failing
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., (*22)
HetrixTools.com has a free, limited plan that will allow ~3 checks per day. See https://hetrixtools.com/pricing/blacklist-monitor/ for details., (*23)
You can set the parameter repeat_notification_after_days in your app/config/config.yml to a non-zero integer to mute the notification email for a number of days if
no change in the list of blacklistings has occured. You will only get the blacklist notification email again once either the mute-duration
has passed or your ip has been been added to or removed from a blacklist., (*24)
Contribute
Contributions are very welcome. Please fork the repository and issue your pull-request against the master branch., (*25)
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 travis-ci.org before you issue the PR, (*26)
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 https://github.com/FriendsOfPHP/PHP-CS-Fixer, (*27)
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., (*28)
php-cs-fixer will check the style of your new added code each time you commit and apply fixes to the commit., (*29)
To run php-cs-fixer manually, install dependencies (composer install) and execute php vendor/friendsofphp/php-cs-fixer/php-cs-fixer --diff --dry-run -v fix --config=.php_cs.dist ., (*30)
ToDos
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, (*31)
Build-Status ec.
, (*32)
Wallogit.com
