Mandrill by MailChimp

This add-on is operated by The Rocket Science Group, LLC.

Scalable email delivery and analytics for applications.

Mandrill by MailChimp

Last Updated: 19 March 2014

Table of Contents

Mandrill is a Heroku add-on for providing scalable email delivery and analytics for apps.

Mandrill runs on the delivery and analytics infrastructure that powers MailChimp. You can get started delivering mail from your app in less than a minute, then use Mandrill’s powerful analytics information to gain insight into the performance and deliverability of your email messages.

Mandrill is accessible via an API and has supported client libraries for Ruby, Python, and Node.js.

Provisioning the add-on

Mandrill can be attached to a Heroku application via the CLI:

The starter plan offers 12,000 emails per month for free. A list of available plans can be found here.

$ heroku addons:add mandrill:starter
-----> Adding mandrill to sharp-mountain-4005... done, v18 (free)

Once Mandrill has been added a MANDRILL_APIKEY setting will be available in the app configuration and will contain the API key to access the Heroku app’s account through the Mandrill API. This can be confirmed using the heroku config:get command.

$ heroku config:get MANDRILL_APIKEY
af5xxxxx-xxxx-xxxx-xxxx-dexxxxxxxxxx

After installing Mandrill the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export MANDRILL_APIKEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the MANDRILL_APIKEY values retrieved from heroku config to .env.

$ heroku config -s | grep MANDRILL_APIKEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Sending with SMTP

Often the simplest way to start sending using Mandrill is to set up delivery using the SMTP protocol. There are libraries for SMTP in just about every language.

Basic settings

Set smtp.mandrillapp.com as the host and either port 587 or 465 for delivery (587 for STARTTLS or unencrypted connections, 465 for SSL-encrypted connections).

Mandrill SMTP connections require authentication to enable delivery. Your SMTP username is stored in your ENV as MANDRILL_USERNAME and your SMTP password should be set to your Mandrill API key which is saved as MANDRILL_APIKEY. Use heroku config to verify that your Mandrill credentials are set correctly.

Example

Here’s a sample configuration for ActionMailer using SMTP:

ActionMailer::Base.smtp_settings = {
    :port =>           '587',
    :address =>        'smtp.mandrillapp.com',
    :user_name =>      ENV['MANDRILL_USERNAME'],
    :password =>       ENV['MANDRILL_APIKEY'],
    :domain =>         'heroku.com',
    :authentication => :plain
}
ActionMailer::Base.delivery_method = :smtp

Using the API with Ruby

SMTP works great and is well supported for sending emails, but Mandrill’s API offers many other features and stats that can be integrated into applications.

Check out the Mandrill API documentation to view full information and Ruby examples for every API call.

Ruby applications will need to add the following entry into their Gemfile specifying the Mandrill client library.

gem 'mandrill-api'

Update application dependencies with bundler.

$ bundle install
...
Using excon (0.15.4)
Using json (1.7.4)
Using mandrill-api (1.0.4)
...

The following example will use the Mandrill API to render a Mandrill template.

require 'mandrill'
m = Mandrill::API.new # All official Mandrill API clients will automatically pull your API key from the environment
rendered = m.templates.render 'MyTemplate', [{:name => 'main', :content => 'The main content block'}]
puts rendered['html'] # print out the rendered HTML

Using the API with Node.js

To access the Mandrill API from Node.js, use Mandrill’s official mandrill-api client library.

Add mandrill-api as a dependency in your package.json file.

"dependencies": {
  "mandrill-api":">=1.0.2"
}

The following example will use the Mandrill API to query for the app user’s information and print out the hourly quota and reputation.

var Mandrill = require('mandrill-api/mandrill');
var m = new mandrill.Mandrill();
m.users.info(function(info) {
    console.log('Reputation: ' + info.reputation + ', Hourly Quota: ' + info.hourly_quota);
});

Using the API with Python

To access the Mandrill API from Python, use Mandrill’s official mandrill client library.

Check out the Mandrill API documentation to view full information and Python examples for every API call.

Add mandrill>=1.0.6 to your requirement.txt file.

The following example will use the Mandrill API to count the number of times test@example.com opened an email.

from mandrill import Mandrill
m = Mandrill()
print(sum([msg['opens'] for msg in m.messages.search('email:test@example.com') if 'opens' in msg]))

Dashboard

For more information on Mandrill’s features, check out the feature overview and documentation.

From the Mandrill dashboard, you can see charts and graphs of your recent email history, see deliverability issues, and change your templates, rules, and sending options.

Mandrill Dashboard

The dashboard can be accessed via the CLI:

$ heroku addons:open mandrill
Opening mandrill for sharp-mountain-4005...

or by visiting the Heroku apps web interface and selecting the application in question. Select Mandrill from the Add-ons menu.

Migrating between plans

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade mandrill:40k
-----> Upgrading mandrill:40k to sharp-mountain-4005... done, v18 ($9.95/mo)
       Your plan has been updated to: mandrill:40k

Removing the add-on

Mandrill can be removed via the CLI. All information will be retained with the account for at least one month. If you accidentally remove the Mandrill add-on, re-adding Mandrill will resume your access to the account.

$ heroku addons:remove mandrill
-----> Removing mandrill from sharp-mountain-4005... done, v20 (free)

Support

All Mandrill support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome via the support link in your Mandrill account or @MandrillApp.

Additional resources

Additional resources are available at: