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 https://mandrillapp.com/templates 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.
[caption id="attachment_66" align="aligncenter" width="620"] A blank Mandrill template[/caption]
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.
https://gist.github.com/Daronspence/dc5836197d96007bdb07
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!
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.
https://gist.github.com/Daronspence/aa13aa3673dcca506096
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 :)