Jan 21, 2013

Transactional Email Plugin for WordPress

Update (3/16/16): Mandrill is now an add-on for paid monthly MailChimp accounts, and is no longer available as a standalone service. Existing Mandrill users have until April 27, 2016 to merge their Mandrill account with a MailChimp account. See this article for additional details, including pricing information and instructions for merging your accounts.

WordPress isn’t just for blogging anymore. You can use WordPress to build a full featured e-commerce site with a built-in social network of forums and groups, along with a job directory and classifieds section. But you already know all that.


What you probably don’t know (or just don’t think too much) about, is the email all those cool features generate: invoices, receipts, shipping notifications, comment updates, account password reminders, and so on. And guess what? All of those emails are "transactional," a realm that MailChimp traditionally does not address.

Until now.

Last year we launched Mandrill, our transactional email service that runs on the delivery infrastructure powering MailChimp. Since launching, we’ve tirelessly extended the platform to support ever more complex use cases for our avid developer user base. People seem to love it!


The core feature enabling all of this, of course, is the Mandrill API. The MailChimp API came a while after the business was off the ground, but the Mandrill API has been part of the product from day one. So an enterprising developer can write some integration code once, then share it infinitely.

Back in April 2012, one of our own developers did this very thing for WordPress, creating a plugin called wpMandrillThe plugin is free, and it routes all of those WordPress emails through Mandrill, giving you deliverability, tracking, reporting, and peace of mind.

It’s been downloaded thousands of times, and we’re proud of the impact it has already had for many WordPress users. Now we’re ready to officially unveil it and let our avid fans know how they can get even more furry-simian-email-love in their lives!

Installing wpMandrill

wpMandrill is a free WordPress plugin that can be downloaded directly from the WordPress repository. Once installed and configured, it overrides the standard emailing function WordPress uses. Let’s install and set it up!

For quick and easy installation, you can use the built-in WordPress plugin installer. Simply log into your site admin, navigate to Plugins -> Add New, then type "wpMandrill" in the search box. You should see the wpMandrill plugin listed in the results and ready to install!

Click "Install Now," wait a tick while it does its thing, then click "Activate Plugin" when it appears after the installation completes.



If you can’t use the WordPress plugin installer for some reason (or choose not to), manual setup is still a breeze. Simply download the plugin and add the wpMandrill directory to your /wp-content/plugins directory in your WordPress code base. Now hop over to the plugins page and activate the plugin there.

Configuring wpMandrill

You’ve got the plugin installed and you’re ready to set it up.

Visit the wpMandrill settings page and you’ll see that it’s pretty self-explanatory, prompting you to set up the necessary things to get it working. The big three are API key, sending domain, and sending address. Let’s take a closer look:

API Key: The crux of this whole endeavor! You’ll need a Mandrill account if you don’t already have one, then you can find your API key here.

Note: You may run into an issue here where you’re getting an "invalid API key" error despite double- and triple-checking your key. This is normally caused because the plugin can’t reach the Mandrill API at all, the error message is just misleading. The API key isn’t invalid, per se, but the plugin can’t validate it due to a connection issue. If this is happening, contact support, and we’d be happy to help you work out the issue!

Sending Domain: You’ll need to add your domain to your list of sending domains here. Note: this is an older requirement that will soon be removed from wpMandrill.

From Email: Of course we have to know who’s sending the email! When it gets to your users’ inboxes, this is the email address it will come from.


The remainder of the settings are optional, but you’ll want to use them to clean up your communications and branding a bit. They are:

From Name: The actual name your users will see as the sender of your emails. Consider making this the name of your site (instead of your actual name), as your users may recognize your brand more than they recognize you.


Reply-To Address: If your recipients hit "reply," this is the address it will go to. Before wpMandrill, such replies usually bounce since WordPress doesn’t actually set up and check an inbox for you (we’ve posted in the past about why this is a bad practice). This plugin allows you to direct those replies anywhere you’d like.

Note: If you don’t set this, replies will just go to the "from email" specified above. Only set this if you want your emails to come from one address, but replies to go to another.

Template: Tired of WordPress’s default, plaintext emails? Here you can specify a template to wrap each email in. Now you can create a template that is just a header and footer, and each email’s content will be injected in between. You’ll need to create templates in Mandrill in advance for them to appear here. For more information on using templates inside Mandrill, check here.

Content: This is a special setting unique to this plugin that turns linefeeds into their HTML equivalent, and you probably want to turn it on immediately. WordPress emails are configured to be plaintext emails with no HTML or formatting in them, so sending them as HTML breaks the formatting and everything gets crammed together. Bad!

We want Mandrill to send our emails as HTML if possible, as this enables some of the more powerful features like open tracking. Your custom templates will probably also be HTML, since that allows you to embed all your lovely brand assets. Turn this option on and the plugin will "fix" the default emails for you, before sending to Mandrill.

Tags: Tags help you track and report on different kinds of email. This is a catch-all setting that adds tags to every email sent. It’s helpful in a pinch if you use this Mandrill account for multiple sites or properties. If you’re unsure, maybe just use the name of your site in case you expand later. If you’re looking to do advanced things with multiple sites, read on.

Click "Save Changes": And you’re all set! Kick back and relax, you’ve earned it, after all.

Testing the Plugin


At this point, the plugin should be working with all of your preferences intact. To be sure, go ahead and send yourself an email from the test form at the bottom. Just fill it out with your email address and a dummy subject line and content, then hit "Send Test." Go check your email and you will be able to readily verify that Mandrill delivered it.

For example, in GMail, it looks like this:


Looks like it was clearly delivered by "*.mandrillapp.com," just as expected!

In other email clients it should be similar, though you may need to poke around a bit to find the raw email message so you can examine its headers.

Note: If you’re curious about that "via" line (or "sent on behalf of" in some email clients), more information (including how to remove it) can be found here.

Why Do I Need This?

So, what exactly have we done here? You’ve never thought about your email before and things seemed fine, why start now? What are we getting by routing our emails through Mandrill instead of sending them as normal?

Deliverability: First of all, in the email world, there’s no such thing as "normal." Many issues can and do arise that you would never be aware of without poring over your log files. Do you even know where (or what) your log files are? You shouldn’t have to.

Good deliverability is one of our primary concerns, and maintaining a good sending reputation for all of our users is essential to our business. Mandrill simultaneously helps you understand these problems and alleviates the need to worry so much about them because you know you’ve got a partner on the case.

Statistics/Dashboard: Of course we track everything sent on your behalf. Then we track what happens over time: "Has the email been opened yet? Did the recipient click a link?" The logical next step is to chart that data for you, so we do!


These stats will be useful to you in a number of ways. They’ll give you early warning detection when something has gone awry ("Why are those charts taking a nose dive today?"), and they’ll be your source of feedback when you make changes to your content ("Wow, clicks are up 20% since we increased the font on that call-to-action!")

But I Run Multiple Blogs, a Store, and a Forum From WordPress!

No problem! In fact: Awesome!

You sound like the kind of power user who can really benefit from the advanced reporting and tools Mandrill exposes.

We’ve written up another post over on the Mandrill blog just for advanced users of the WordPress platform like yourself. We go into how you might set things up for multiple installs, domains, and properties, and some techniques for customizing, tracking, and improving the communications you send from them.

What If I Don’t Use WordPress?

That’s just fine, too. There are a couple of great integrations that leverage Mandrill for other popular blogging platforms and CMSes:

And new integrations can be built quickly by any competent web developer. That’s the beauty of a simple API!

More Features and Integrations Ahead

Are there any features you wish wpMandrill had?

What about other platforms? Where would you like to see Mandrill go next?