Crafting Personalized HTML E-Mails with wpMandrill

Recently, I’ve been working on a new little side project called ToDo, a small SPA that allows you to create and manage a ToDo list. It utilizes the new WordPress JSON REST API and it’s awesome. You should definitely check it out!

Edit: ToDo in its current form has unfortunately been “closed”. While you may still find something at the link, I’m not doing anything with it, and will be replacing it with something new, hopefully, in the very near future.

From the ToDo website, there is a button that will let you invite users to come try it out. You enter an email address and away it goes! Now, rather than send some boring plaintext emails, I decided I wanted to do something a little fancier. I’m a huge fan of Mandrill (made by the folks over at MailChimp) for sending small “transactional” emails. Stuff like registration emails, update emails, etc. Mandrill has a free tier (like MailChimp) that allows for 12,000 free emails per month. For this reason, I install it on 99% of the WordPress sites I create. This allows us to bypass the horror that is sending emails on shared hosting and it doesn’t cost my clients a dime.

Today we’ll be exploring one of the lesser used features of Mandrill (at least from a WordPress perspective) and creating some customized invitation emails to send to prospective users! I’m going to assume you have the official wpMandrill plugin already installed and configured with your Mandrill API Key.

First, let’s log into Mandrill and create the template for our emails! Navigate to and create a new template. Give it a name and hit the “Start Coding” button. You’ll be presented with a screen containing some meta data fields and a small code editor text area.

A blank Mandrill template
A blank Mandrill template

Now, if you aren’t familiar with coding emails, this will probably be pretty painful, but most email clients will strip the <style> tag from the <head> of the email. You’ll need to inline all of the CSS for your elements. This tutorial isn’t going to focus on how to code emails so much as how to customize them. Just know, that if you’re emails don’t quite match the preview, then it’s probably your email client stripping out information.

<h2 mc:edit="title"></h2>
This message was generated from <a href="">ToDo App</a>. Come by and check out what we're all about 🙂
<div mc:edit="main""></div>

view raw


hosted with ❤ by GitHub

Above is a simplified version of the template used for ToDo. Notice the mc:edit attributes on some of the elements. These are the hooks that allow us to dynamically insert our content into the email. Note, mc:edit="main" is required by wpMandrill, however, you can create as many custom attributes as you want after that.

Now that you’re template is complete and you’re happy with the design, let’s add some dynamic content! For my template, the mc:edit="title" attribute is being used to dynamically add a header to the email to describe what the email is about. For example, when sending an invite, I could add, “You’ve been invited”, while for a password reset, it could say, “Reset Your Password”, instead.

Navigate to your WordPress dashboard and then to the wpMandrill settings page. Select your newly created template from the “Template” drop down and then open up your favorite code editor and get ready for some excitement!

Change the wpMandrill Template


Now, the functions we are about to create can be added either in the functions.php file or in a custom plugin. I highly suggest the latter, but it’s up to you. The code is fairly self explanatory and the inline comments should explain everything you need to know.

# You'll need PHP 5.3+ to run this code as is.
// This action fires for an ajax event. Change it to whatever hook you need.
add_action( 'wp_ajax_todo_invite_friend', function(){
// We're only going to apply the filter when this specific action is triggered
add_filter( 'mandrill_payload', function( $payload ){
$template_content = $payload['template']['content'];
# $payload['template']['content'] # Multi-dimensional array of MC tags
$template_content = array(
// this corresponds to mc:edit="title"
'name' => 'title',
// this will be the new "title" content
'content' => "You Have Been Invited!"
// Add our new template tag content to the $payload
array_push( $payload['template']['content'], $template_content );
return $payload;
} );
$email = sanitize_email( $_POST['email'] );
$sender = get_userdata( get_current_user_id() );
$sender = "{$sender->data->display_name} ({$sender->data->user_email})";
// the second argument of wp_mail is passed to mc:edit="main" in our template by default
$success = wp_mail( $email, "You've been invited!", $sender . " invited you." );
// AJAX return values
if ( $success ) {
} else {

In my example above, the code is ran for a specific AJAX event, but by changing the action hook to something else, you can easily move this code wherever you want. If you want to provide a default value, attach the filter to the init action and pass your values there. While I did not document it above, note that it is also possible to filter the email template that is used as well. Just know that you will need to change that value if your site utilizes more than one template.

Hopefully you can see jut how powerful and useful Mandrill is, as well as a couple of ways that you can utilize it in your WordPress projects. If you have any questions, be sure to leave a comment below and keep the discussion going 🙂

Author: Daron

Professional software developer with extensive experience in Laravel and WordPress. When not writing code, he enjoys Netflix and playing Nintendo. He is also available for freelance opportunities. Get in touch to hash out the details.

3 thoughts on “Crafting Personalized HTML E-Mails with wpMandrill”

  1. “Mandrill has a free tier” is no longer true.

    It disappeared during July 2015, while other competitors still have their free tiers.

      1. Found out by accident, and not something they have been open about.

        Existing customers do seem to be able to continue using it for free – at least for now.

Leave a Reply

Your email address will not be published.