Mailer - Drivers - Mandrill

Notes

The Mandrill Driver has a few components that you need to set up / be aware of.

This is the default driver. You do not need to do anything, although you could be explicit and include it in your .env file as:

ENSO_MAILER_DRIVER=mandrill

Mandrill Setup

Ideally, you will have a Mandrill account for any app with an installation of the Mailer. It 'can' work with many installations pointing to the same Mandrill account, but given sending limits it is strongly recommended that you do not.

Environment Variables:

Mandrill's way of feeding back into the system is via webhooks (for any email sent to more than 10 people, so we're just using them for everything). As such, there is a webhooks controller (that you shouldn't need to touch) with some settings you will need to set up.

This is an API key for mandrill, set up through Settings -> New API Key

ENSO_MAILER_SECRET="KEY_HERE"

This is the key of the webhook. It should be displayed on the Webhook entry in Mandrill (See below)

ENSO_MAILER_MANDRILL_KEY="KEY_HERE"

This is a tag to add to any emails sent via this installation of the Mailer. This should allow for sending other mail via the same account, and technically all for sending multiple different Mailers through one account, although it is strongly recommended that each installation has it's own account. Defaults to EnsoMailer if not set. This will be used to populate the Mandrill Rules

ENSO_MAILER_MANDRILL_TAG="EnsoMailer"

If you are developing the site and want to test webhooks. You will need to install and use ngrok. Due to this, you will have to specify the current ngrok url (see below) in the .env file as:

ENSO_MAILER_MANDRILL_URL=""

In non-development environments, you do not need this variable. The Mailer will user the domain of the current url coupled with the webhook route to build the correct url.

If you are building for use on a staged site (or any other site with basic-auth enabled), you will need to turn off basic auth for this to work. There is no way to add extra authentication headers to the mandrill webhook requests.

Once you have an account and environment set up, you will need to:

Mandrill Webhook

On your mandrill account go to Settings -> Webhooks and add a webhook. This should not have any triggers set. If it does, it will trigger on every email that matches the event, and not just the Mailer emails. This shouldn't break the Mailer, but will gather a lot of unecessary MailEvents in the database.

Note: If you are setting this up the a development environment, see the notes at the bottom of this page with regards to the Post To URL

Mandrill Rules

Mandrill can be made to send event to specified webhooks under specific conditions. On your mandrill account go to Outbound -> Rules.

You will need to set up 8 rules (one for each of the events sent, bounced, soft_bounced, opened, clicked, unsubscribed, spam and rejected). You don't need the other events.

Each rule should, on the condition that it contains the tag you specified in ENSO_MAILER_MANDRILL_TAG, send the event to the webhook you have created. Unfortunately, you cannot set one of these up for multiple events at once.

Additionally, on the 'Sent' event, you could also set set open tracking, set click tracking, set css inlining and add unsunscribe footer settings to 'on'. This will act as double insurance against minor API changes.

ngrok

To use the webhooks functionality from the development environment, you will need to install ngrok. Ngrok is a tool that sets up a tunnel, making your developement machine available at a generated url. The limitation is that when each time you take your server down and then up again anad re-run ngrok, you will have a different URL.

Due to this, whenever you start your development environment, you will need to update the webhook associated with your site. This url is used to validate that a webhook comes directly from Mandrill, as mandrill users the url it's sending to as part of the key generation process.