Here’s Your Mandrill Template Migration Tool

In the weeks since MailChimp announced that they have eliminated Mandrill as a stand-alone offering, our team has heard from lots of developers looking for a Mandrill alternative. And, as our lead product manager Amie Durr wrote about subaccounts and other enhanced SparkPost features, it’s been epic feedback that’s really helped us focus on what developers need to be productive.

And near the top of the list is making it easy to import Mandrill templates into SparkPost. That’s something we’ve heard, loud and clear. I sometimes think about email templates like Gollum thought about his ring: precious and powerful, and messing with them can have tricky side effects. Along with branding and structural layout, templates also are shot through with personalization markers—we call them substitution variables, Mandrill says merge tags—that are designed to tailor each recipient’s message with content meant just for them. When you couple that intrinsic complexity with the fact that our respective platforms work differently, you might fear you’ll have a potentially challenging migration task ahead, especially if you have lots of templates.

So, that’s why I’m really happy to announce our newest community project: an open source Mandrill template migration tool that makes it really easy to import Mandrill templates into SparkPost. (Or, as I like to call it, the Mandrill-to-SparkPost Templatizer 3000. That’s MST3K for short ;-).

Shoutout to @SparkPost for their @MandrillApp template migration tool, saved so much time! ?

— David Ko (@dko26) April 27, 2016

For the impatient and technically minded, you can just grab the code from GitHub and follow the README. For the more prudent, read on for details about how it works, how to use it, where to get help—and also how you can help out with this project.

Deployment: Where Can I Get MST3K?

First things first: where can you get your hands on the tool?

The Easy Way: Heroku

If you’re developing with Heroku, you can just click this button to deploy MST3K into your Heroku account. Done.

Once the Heroku deployment completes, you’ll be presented with the web UI.

The Other Way: Run Locally

If you would rather deploy the tool into your own environment, here are the minimal steps. Note: you’ll need to have git  and Node.js 0.12+  installed.

$ git clone --recursive https://github.com/SparkPost/mandrill-sparkpost-templates.git
$ npm install
$ npm run start

Whether you deployed in Heroku or locally, the UI will look the same:

How-To: How Do I Use MST3K?

Translating Mandrill Template Content

Once deployed, the simplest way to use the tool is interactively. Choose the “Translate Template Text” option. Paste your Mandrill template code into the left pane of the UI and hit “Translate!” Your translated output will be presented in the right-hand pane, ready to copy-and-paste into SparkPost.

Automating Mandrill Template Migration

Now, one-off, interactive conversions are all well and good, but you might prefer to automatically pull a template from Mandrill, translate it, and upload it directly into your SparkPost account. You probably want the migration to take both the plaintext and HTML template code into account, as well. I got you. Choose the “Migrate a Template” button on the main menu to begin. Here’s how it works:

Mass Mandrill Template Migration

OK, but what if you have lots of templates to migrate all at once? Because the UI is just a presentation layer on top of an API, it can be automated to fit your needs. Here’s an example which uses curl to call the migrate API endpoint directly:

$ curl -X POST http://localhost:3000/api/migrate -H "Content-Type: application/json" -d '{"mandrillAPIKey": "...", "sparkPostAPIKey": "...", "mandrillTemplateName": "migrateMe"}'

{"result":true}

Capabilities: What Can and Can’t MST3K Do?

So, what template capabilities translate from Mandrill to SparkPost?

If you are unsure of whether your template is migratable, the simplest option might be just to try it: the tool attempts to present useful error messages.

MST3K is designed to translate a Mandrill template that uses Handlebars-style syntax into equivalent SparkPost templates. Here, “Handlebars syntax” means templates that use curly brackets around their variables like this {{firstName}}.

To learn more, or for reference as you read on, it might be helpful to bookmark Mandrill’s Handlebars documentation and SparkPost’s substitutions variables docs. And, the official Handlebars documentation as well. Note that Mandrill has made a few syntax additions which are marked below as “Mandrillisms.”

The rest of the section gives samples of supported Mandrill syntax along with some equivalent SparkPost terminology for reference.

Basic Template Handlebars Syntax

Our MST3K migration tool can translate the basics like this:

Hi {{firstName}}

Hi {{firstName}}

{{#if newUser}}
Welcome to
{{else}}
Welcome back to
{{/if}}
our little block of code.

{{if newUser}}
Welcome to
{{else}}
Welcome back to
{{end}}
our little block of code.

Our topics today are:
<ul>
{{#each topics}}
  <li>{{this}}</li>
{{\each}}
</ul>.

Our topics today are:
<ul>
{{each topics}}
  <li>{{loop_var}}</li>
{{end}}
</ul>.

Mandrillisms

Mandrill made a few additions to vanilla Handlebars which we can also translate:

{{#if canTimeTravel}}
You might be a particular Scottish physician.
{{elseif saysWubaLubaDubDubAlot}}
You're probably a Rick.
{{else}}
Just a mortal, huh?
{{/if}}

{{if canTimeTravel}}
You might be a particular Scottish physician.
{{elseif saysWubaLubaDubDubAlot}}
You're probably a Rick.
{{else}}
Just a mortal, huh?
{{end}}

{{#if `numEars > 2`}}
You're clearly not local.
{{/if}}

{{if numEars > 2}}
You're clearly not local.
{{end}}

Inline Helpers

Mandrill has a set of “content formatting helpers” which our migration tool understands but ignores, because there is no equivalent in SparkPost. The helpers currently accepted are the text case conversions: upper , lower , and title . The result post-translation is that those helpers are removed. Here’s an example:

Unsupported Elements

Finally, there are couple differences between a Mandrill template and a SparkPost template to be aware of when migrating:

• Inline helpers: the url, date, and striptags helpers have no equivalent in SparkPost.
• Block helpers: the unless and with block helpers have no equivalent in SparkPost.

MailChimp Template Syntax

By the way, what about MailChimp syntax? Although our support for MailChimp syntax is more limited, we do have early support for MailChimp syntax, thanks to a community contributor. Woot! Our community is pretty epic. Not sure if you’re using Mandrill or MailChimp syntax? Here’s the test: if your templates have {{curly brackets around substitution variables}}, you’re using Mandrill syntax. On the other hand, if you have variables in your template like this: *|firstName|*, you’re using MailChimp syntax.

Help: Where Can I Learn More about MST3K?

As always, if you run into an issue, you have a how-to question, or you’d like to talk your situation through, come speak to us on SparkPost’s community Slack channel. For template and other code samples, integrations, and more, be sure to check out the SparkPost Developer Hub.

Contributions: How Can I Help Improve MST3K?

As with all community projects, MST3K stands on the shoulders of giants. To help make the tool as awesome as possible, we welcome all contributions from Mandrill and SparkPost users alike. Whether you open an issue, submit a pull request, or come share your experience with the community, we’d love to hear from you.

Let’s Build Something Awesome!

So, there it is: the Mandrill-to-SparkPost Templatizer 3000 is ready to help folks in need of a Mandrill alternative to make it easy to migrate Mandrill templates to SparkPost. I hope this addition to your toolbox serves you well!

—Ewan