As a Sales Engineer at SparkPost, I have a lot of discussions with prospects that represent software platforms which send emails on behalf of their customers. These include a variety of applications from your typical Email Service Providers (ESP), CRM platforms for various verticals, any sales automation systems and platforms that support healthcare and various non-profits. One of the central questions I get is how they can share a group of standard templates with their clients? While the answer is not very difficult, it always seems to lead to a bunch of hand-waving and list of definitions of the customer’s terms. While I expect to have many of those discussions moving forward, I thought I would write this blog in order to shed some light on the subject.

Ok, let’s start with the ground rules:

  1. Each SparkPost account has ONE master account. The company paying SparkPost is typically the owner of that master account.
  2. The SparkPost account can then have many subaccounts. Subaccounts are usually either company departments that want to keep email sending separate from one another or clients that are sending email through your platform.
  3. Templates are emails that can be stored in the SparkPost platform for later use, and typically allow for substitution data to be injected into the email just before sending. They don’t have to be stored on the SparkPost platform to be used, but for this discussion they do. It’s also important to understand these rules around templates:
    1. Templates created by a subaccount are owned by the subaccount and can only be edited by the subaccount.
    2. Templates created by the master account can be one of these three states:
      1. Owned and only seen by the master account.
      2. Can be given to a subaccount which then allows that subaccount to edit that template as if they created the template. This also means that the master account loses the ability to make changes to that template.
      3. Can share the template with all subaccounts. This gives all subaccounts the ability to read/use the template but can not make changes to the template. If the master account makes an edit to the template, all subaccounts will see those edits.

The typical scenario is easy enough; The the master account wants the ability to share a template or a set of templates with a specific subaccount or all subaccounts. The way to do this in SparkPost is for the master account to select which template they want to share, then duplicate that template and give it to the subaccount.

To get here, I selected the specific template from within the SparkPost UI and pressed the duplicate link/action. It then presented me with the template along with several input fields, one of them being how I want to assign the template. I picked, ‘Assign to Subaccounts’ then entered in ‘Mr Pickles Sandwiches’ as the target subaccount. Once I save this template, Mr Pickles Sandwiches will then have sole ownership of the template. I would then do this process for each template. The SparkPost ‘template’ API would allow me to automate this process if I created a small app that read a targeted list of stored templates for sharing, looped through each template name to read a copy of each template, then created a new template using the subaccounts name in the subaccount field.

The other scenario is when the master account wants to share the template with all of the subaccounts. This is very simple. When creating the template, the user simply needs to select, the ‘Share with all subaccounts’ radio button (shown in the picture above). That now gives all current and new subaccounts the ability to read/use that template. There again, the template can be brought into SparkPost via the ‘template’ API and the option for sharing can be turned on at that time allowing for a fully automated process.

You can find more information about SparkPost templates in our documentation.


Questions on templates or subaccounts? You can check out our documentation above or ping us in our community slack channel.


Or, How To Put Templates In Your Templates

Removing code duplication is one of the most satisfying parts of refactoring and programming in general. The past few decades are littered with a variety of ways to detect and reduce duplication for many different types of code. Solutions range from IDE-assisted refactoring on the more complex side of things to various strategies for pulling in content fragments like header and/or footer, so common content can be centrally managed.

By now it’s perhaps obvious what we’re going to talk about in this article: how to support includes in SparkPost Templates. A quick disclaimer, this support will be provided as part of a client library, instead of directly in our service.

I’ll be modifying our Go client library (which I maintain) with this new functionality. While we’re in there, it’s only slightly more work to allow writing your own macros, with the function signature func(string) string – so let’s make some Macros!

SparkPost Templates: How do they work?

The short answer is they’re basically like Handlebars templates (docs here on our variant). The longer answer is that under the hood, while they technically support more stuff (like user-defined macros), it would be, let’s say, “unwise” to allow our users to write their own macro code that would execute on our system.


As our company has evolved over the past few years from traditional software to become a cloud-based service provider, parts of our mindset have shifted too. Before our cloud shift, a feature like Template includes would have been implemented “inside the box”, meaning as a customization inside the email server itself.

While this approach is certainly still possible, the system stays simpler and more flexible when functionality can be pushed outwards. Instead of building one specific “in the box” feature, when we can empower customers to build the features they want most, that lets us innovate elsewhere.

The Search For Template Includes

My first thought when starting to build this feature was: “Ok, what library am I going to use?” – however, it turned out to not be quite that simple. What we’re going for here is to allow users of our client library to pre-process templates before calling our API. This means only Handlebars blocks with locally-registered macros should be interpreted and replaced, not every block in the template. None of the templating libraries I found supported this kind of partial template execution.

Thankfully, the code to detect Handlebars blocks (see Tokenize) isn’t too out there, which makes partially executing templates quite a bit easier. Here’s an example of a made-up template you might want to partially execute before sending an email:

An advantage of this kind of approach is ease of integration between existing systems and SparkPost, letting users continue to use the same tools they’ve always used to build content. As long as the system can export over HTTP, content can be pulled into an email template. This is a somewhat contrived example, and I’m sure you’ll come up with some clever ideas for macros that we haven’t even considered. Let us know what you build!

The Template For Templating Templates

That’s all well and good, but how do you use the thing? The client library’s default behavior doesn’t change, so you’ll need to explicitly add calls to pre-process strings with your shiny new Macros. Here’s a list of the types and functions added for this feature:

Usage is simpler than the four (4) exported functions would imply. Check out the tests for examples. You’ll need to register some Macros with the appropriately-named  Client.RegisterMacro , and then call  Client.ApplyMacros to perform pre-processing on whichever strings might contain your Macros. The other two functions are there in case you’d prefer to do things differently than  ApplyMacros does – like having Metadata take precedence over  SubstitutionData , for example.

What’s Next For Template-y Templates?

You’ll notice the triple-curlies in the example template above. That’s a bit of a head fake. As of this writing, client-side macros treat double- and triple-curlies identically, with no escaping. For consistency with how SparkPost (and Handlebars) templates work, doubles should escape HTML in the substitution value, and triples should turn off the safety.

The careful reader will also notice that the feature, as written, is suitable only for single-Recipient Transmissions, or for multi-Recipient Transmissions using Templates that don’t have per-Recipient placeholders nested inside custom Macros. Supporting this use case would likely require modifying the Transmission payload to contain dynamic_html for the per-Recipient pieces, or unrolling the Transmission API call so the client library makes one call per Recipient.

Did you enjoy this post? Got a clever Macro to share? Let us know by commenting, or start a conversation on Github or send us a tweet.


We receive a continual flow of comments, use case questions and feature requests from our community. One constant we have identified while listening to you all is that you each come from somewhere, usually another email service. In response, we published migration guides for Mandrill, MailGun and SendGrid. We also heard that moving email templates between services was a regular pain so we built a Mandrill template migration tool to help with that.

We had some nice feedback from those efforts so, to build on that, I’m excited to to announce our new SendGrid template migration tool. Now people coming from SendGrid can bring their transactional and marketing campaign email templates with them to SparkPost. Read on for details on how it works, where to get it and how to get help.


For the impatient and technically-minded, you can grab the code from GitHub and follow the deployment steps in the readme. You’ll need Node.js installed as a prerequisite. Happy translating!

Deployment: How Do I Get It?

Using Heroku

If you’re a Heroku user, you can just click the purple “Deploy to Heroku” button below or from the GitHub Repo to bring the tool up in your Heroku account. Quick and easy.


Running It Yourself

You can also run it like any other service. Here are some minimal steps to get you started. You’ll need Git and Node.js installed.

Once started, you can access the UI from http://localhost:4000/. Incidentally, the app is the same whether running locally or on Heroku:


How To Use It

Translating SendGrid Template Content

The simplest way to use the tool is just to translate a piece of SendGrid template text into its SparkPost equivalent. To do that, choose the “Translate template text” button to show the side-by-side translation page. You can paste your template into the text box on the left, select “Transactional template” or “Marketing template” depending on the type of content you want to convert, then hit “Translate!” and your SparkPost template will appear on the right.


Migrating a SendGrid Template Into SparkPost

The app can also migrate transactional and marketing campaign templates directly from your SendGrid account into SparkPost on your behalf. Naturally, you’ll need both SendGrid and SparkPost accounts to pull this off. Your SendGrid API key needs Template Engine permission if you’re migrating a transactional template and Marketing Campaigns permission for a marketing campaign template. Your SparkPost API key needs Templates Read/Write privilege to save the translated template on your account.

Identifying SendGrid Templates By ID

As a quick aside, you’ll need to know how to identify your SendGrid templates to migrate them into SparkPost. SendGrid’s transactional templates are identified by a UUID which is visible under Templates -> Transactional beside each template. Marketing Campaigns are identified differently. Campaigns each have an integer which is visible in the editor URL for that campaign. You can see each marketing campaign’s URL by visiting Marketing -> Campaigns and hovering over that campaign’s link.

…and now back to the matter in hand. Once you have your API keys and template ID, choose the “Migrate a template” button in the migration tool to show the template migration page. Paste in your SendGrid API key, SendGrid template ID and SparkPost API key into the form, then click the “Begin migration” button. This will bring the template over from your SendGrid account, translate it into SparkPost-speak and deposit it into your SparkPost account.


Automating Migration

So much for mouse-driven migration. Let’s say you actually have 10 or ~500~ 300 templates to migrate. That’s a lot of clicking around. Instead, you could use the migration tool’s API directly to rip through all your templates at once in an automated, repeatable manner. Here’s a sample HTTP API call which migrates a transactional template:

Here’s the same thing in a convenient cURL command:

The Devil’s Details

Not all email template features were made the same so there will always be some interesting edge cases to consider as you migrate. Here are a few key differences to consider when coming from SendGrid to SparkPost.

  • SparkPost uses a single template featureset for both transactional and marketing content.
  • SparkPost templates support logic, iteration and structured substitution variables so once you migrate, you can do more with your email.
  • SendGrid transactional templates have several different ways to personalise each email including the body tag, substitution variables and sections. SparkPost uses a simpler model: you only need substitution data to personalise each template for a recipient.
  • SparkPost handles only “global” unsubscribes and not SendGrid’s preference group concept.

You can also read our SendGrid migration guide which covers the broader task of bringing your email activities over to SparkPost.

Getting Help And Learning More

As always, if you run into an issue, have a how-to question, or you’d like to talk your specific situation through, come speak to us on SparkPost’s community Slack team. If you have a tool-specific issue or query, you can open an issue in GitHub. Our template syntax documentation is here and also check out our sample templates.

Contributions: Giving Back

The SendGrid template migration tool (which really needs a better name) is a community project. For it to be as useful as absolutely possible, we’d love to hear your feedback and we’d especially love your own contributions.


Zillions Guide Blog Footer

Saving Time with Substitution Data and Templates

If you’ve been around systems development for any amount of time, you know there’s a lot of inertia when it comes to how transactional email or other messages are generated by business systems. Even today, many companies that use services like SparkPost or any email service provider (ESP) as a “pipe” (be it dumb or smart), build the full email in one of their back-end applications then connect to the ESP via SMTP in order to send the email. If the email is something like an invoice, password reset, shipping information or abandoned cart, the email is personalized to that user. If the communication is more akin to an advertisement of products it may or may not be personalized to leverage the user’s search or purchasing patterns. Either way, these emails are typically built by homegrown systems that construct the full email content into a single SMTP call to the ESP. As discussed earlier, this connection between code and the content creation makes it very difficult to make changes.

Over the last few years, ESPs have started to provide REST APIs that allow companies the ability to create content structures, or templates, via the ESP’s UI (or submitted via another REST API). Following the creation of these templates the application sends data to the ESP, identifying which template to inject the data into.

The Old Way [Well, Current Painful Way for Many]
Development or IT builds and maintains email creative and personalization content


Any changes to the email must go through the change request process, development process, QA process, and fight all other development projects!

The new way is to separate out the creation/updates of the creative and obtaining the data for personalizing the content.


The high level changes that need to take place from a development perspective are:

  1. Gather the data to be sent and format appropriately for the ESP. For SparkPost, this would be a json structure (see example below).
  2. Add supporting information:
    a. Which template to use and/or campaign name
    b. Turn on/off options like click or open tracking
    c. Optional metadata and tags that can be used to help understand user email behavior
  3. Send json formatted substitution data via REST API

One of the cool options that you can do with many of these REST APIs is that you can send more than one email at a time. For instance, SparkPost allows you to send the request for thousands of emails all at the same time, as long as they use the same template. This allows the developer to batch emails in groups instead of making a REST API connection for every email.

SparkPost also supports the concepts of metadata and tags into the system. Tags are high level identifiers that describe the overall email campaign; for example, Newsletter, Invoice or Welcome would be good tags. On the other hand, metadata is a key-value pair of data that is often used to describe that individual email. For example, if you wish to track what category of products are in the email being sent to this user you may have a key value pair of “category” : “electronics” (see example below). When the user opens the email or clicks on a link, the metadata (and tags) are added to the information logged for that email which then in turn can be sent to your back end databases via webhooks which are small chunks of data that is sent/pushed from the mail system to your applications via HTTPS for processing. SparkPost has about 19 different webhooks that handle everything from email injection, creation, bounces, feedback, opens and clicks. Our developer hub has more information about SparkPost’s webhooks support.

Hint: Metadata fields can also be a multi-level array AND they can be used in your email as substitution fields.

So how does the HTML template (email) actually use the data being sent by your applications? Great question. Many template systems, including SparkPost, use a familiar handlebars-style syntax. Start and end markers are defined as double curly braces; for example, {{billing_zip}} will replace the user’s actual zip code that was sent as substitution data via the REST API into the HTML (or text) email before sending out. Of course more complex replacements can take place if there are arrays of data which would be common for emails that might list a set of features within a list of products but that description will come in a later blog post. Right now, if you want more info, please refer to our substitutions reference documentation.

A real example of using substitutions within an HTML email with the data below might look like:

With this new approach, marketing can take charge of the creative and let development focus on pulling the data together.  When legal or marketing need to make a change to the wording, it’s all up to them now and not development.  That sounds like a win-win to me!  To further simplify a development team’s life, a good practice is to overload the JSON entry with lots of information about the user and not worry about matching the exact information that the template is looking to use.  If the template doesn’t use the data, so what?  This simplifies the coding for development tremendously.  I wouldn’t go crazy with sending every stitch of info you have on a user, but adding extra info in order to minimize a bunch of code branches won’t hurt anyone.

Sample Json for a single email recipient

Sample web hook event for a bounce event on the mail system

So that is the introduction into leveraging substitution data and templates to separate the work of obtaining data for personalized emails and the creative for those emails.

In the next blog, I’m going to talk about ways to use substitution fields at a global level which can be used to change colors for branding or white labeling, as well as to simplify management of headers, footers, and multi-language issues.

Happy Sending

Jeff Goldstein
Senior Messaging Engineer

Questions on using substitution data and templates in email personalization? Give us a shout on twitter or comment below.

Zillions Guide Blog Footer

Skeleton anatomy as metaphor for email template

If you search the Internet for “free email templates,” you’ll find a lot of ideas. I mean A LOT of ideas. And, I’ve got to say that a number of these templates are perfectly serviceable–they look nice, they’re more-or-less responsive to mobile layouts, they give you some bits to customize and tailor to your brand. All good, right? Well, before you grab one of the many free examples of email templates, take a moment to consider whether it’s more than a pretty face.

What really makes a successful email? There’s not just one formula for success—there’s a reason email marketing professionals are in high demand. It’s a complex topic that really depends upon the nature of your business, your brand, and the needs of your customers. But those intangibles aside, most successful emails hang on the skeleton of workhorse email templates that meet a few key criteria.

Our skeletons are what keep us from being a formless masses of ooze (at least that’s what I hope for myself, anyway)! It can help to think of an email template as playing a similar role. It’s what gives a message it’s structure, and like a skeleton, it features a head, body, and feet. Let me walk you through several of the features that your email template should include.

The Email Template Header

It makes sense to start with the header. Not simply because it comes first, but also because it contains the cues your recipient will see in the inbox. Though literally a small part of the template, it should be crystal clear about what value the reader will get from reading your message. Getting the header right will ensure whether she or he takes the time to open the message. Getting its details wrong will be a deal-breaker, no matter how good the rest of your email message.

  1. Use a recognizable and friendly “from” name and address. It’s hard to overstate how much this matters, and it frankly shocks me how many major brand companies get it wrong. A bare “[email protected]” address in your email template makes it impossible for a user to reply. Just as importantly, it sends the message that this is a bulk email unworthy of the recipient’s attention. Instead, use the brand name that your customers would expect.
  2. Use the right “reply-to” address. When you or I send a personal email, a recipient’s reply generally comes right back to us. But, handling replies to high volume marketing and transactional emails is not nearly so simple. Your email template should not only avoid the “do-not-reply” trap described above, but also make sure that replies go to an address that’s able to process it. Depending upon your business, your email template could be populated with a reply address for customer service, sales, or even your CEO—or it could be a unique endpoint that’s tied programmatically into that individual recipient’s help desk or CRM record.
  3. A good template encourages you to create a killer subject line. Entire books have been devoted to the art of creating a compelling subject line. What works for one business could be very different than another, but your email template should make it easy to follow a few consistent rules: keep it short and to the point. Not only does that make it easy for the reader to get the point, but it also works for a variety of devices like mobile devices. The sweet spot is about a half-dozen words, or less than 50 characters.
  4. Don’t waste the “preheader” text. Sometimes called a “snippet,” the preheader text is usually the first line of copy that appears as a preview in the inbox or in your message. Think of it as a subtitle to your subject line. There’s room for less than ten words, or about 75–100 characters. Too many stock email templates waste that space with boilerplate like “View this message in web browser.” Yours shouldn’t do that. Replace the stock preview text with a line that clearly and compellingly previews the message content.

The Email Template Body

Now comes the body of the email. If your recipient has responded to your subject line and other header information, the body of your email template is where you have a chance to really tell your story.

  1. A good template is visually simple. A responsive design, single-column layout works consistently in both desktop and mobile email. Moreover, using white space and generously-spaced elements lend both visual clarity and focus, but also make your links more usable for someone tapping with a finger.
  2. Your email template should contain placeholders for personalization. At a minimum, that means personalizing the salutation and perhaps a few bits of placeholder text like store locations. A more sophisticated template could contain highly complex rules that personalize offers and content based upon multiple criteria your customer database and business systems might contain.
  3. Your email template should use images strategically. It’s true that a picture’s worth a thousand words (and supports our next template tip below), but multiple images quickly overwhelm your message. The best templates use a structured approach that emphasizes a “hero image” or another simple way to scale gracefully on a variety of devices. And as much as you love your logo? Use it just once.
  4. A good email template helps you enforce a concise approach to copy. If you’re a writer like me, it’s tempting to craft a perfect letter with a detailed narrative structure. Don’t do it. It’s not about dumbing it down—it’s about being pragmatic. Concise copy not only scales well to mobile devices, but it makes it a lot easier for your customer to take the action you want him or her to take. After all, your email is just one of perhaps hundreds in her or his inbox, so demonstrate you respect your recipient’s time.
  5. Your template really needs to focus on one easy call to action. Most emails aren’t self-contained islands; they’re meant to drive some other action, like visiting a web site or engaging with an app. The most successful email templates make that call to action extremely clear, easy to activate, and a natural part of the message.

The Email Template Footer

It’s easy to overlook the message footer as containing a lot of boilerplate and other items nobody reads. But the truth is, the footer of an email template is where a number of message must-haves reside. Without them, your email might suffer customer spam complaints, deliverability hits, and even legal penalties.

  1. Contact information for your company is a must-have in an email template. Letting the recipient know how to contact you not only is common courtesy that reinforces trust in your brand. It’s also a legal requirement in most jurisdictions.
  2. Your email template needs to contain a clear statement of responsibility that tells the recipient who sent this message and why he or she received it. Believe it or not, a user might not remember when or how he or she interacted with your brand and chose to receive emails. This sort of statement solves that problem, and when done right, also is a great way to reinforce the relationship you have with your customer.
  3. Every email template needs to show clear, easy-to-find unsubscribe and messaging preference links. Laws in the United States (and most other markets) require that all commercial email messages include a simple mechanism for subscribers to unsubscribe or opt-out. Even for transactional email messages, making it easy for your customer to tell you whether she or he wants your email is the best path to success. Don’t obfuscate or make unsubscribing difficult; that approach will hurt you in the end.

A Good Template Helps You Deliver Great Emails

A good email template is the foundation of a repeatable workflow and success with your emails. Including these key elements will help give you the structure you need to focus on what really matters: communicating a message that connects to your customers and drives the sort of engagement or response your business needs.

What would you like to know about email templates and crafting successful email messages? Let me know! I’d love to hear your point of view and the sorts of questions you run into.

By the way, if you’d like to take a deeper dive into the best practices for emails that really work, be sure to check out some of these great resources:

P.S. If you’ve already invested time and effort into creating great templates in Mandrill, I bet you’ll be glad to know our developer team created a really useful Mandrill-to-SparkPost template converter tool.


Dev Survival Guide Blog Footer


Mandrill Template Migration

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 ;-).

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.

Deploy to Heroku

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.

Once the install is complete, you can access the web UI at http://localhost:3000/ .

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


Mandrill-to-SparkPost Template Tool MST3K UI

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.


Mandrill-to-SparkPost Template Tool MST3K Translation UI

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:


Mandrill-to-SparkPost Template Tool MST3K Migration UI

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:

You also can call the /api/translate  endpoint in a similar manner. For much more detail on the API, checkout the README and the code on GitHub.

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:

Variable substitution
Conditional logic


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

Conditional expressions

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:

Translated result
{{upper firstName}} {{firstName}}

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!


Biz Eval Guide Blog Footer


advanced email templates

This post is directed at the developer who wants to get the most out of SparkPost’s email template capabilities. It is assumed you are comfortable with reading JSON content and following basic programming flow. As terms that maybe new to you are introduced like RFC 5322, the text is linked to its source reference. With that out of the way, let’s jump right in.

SparkPost’s template and transmission capabilities make sending emails straight forward. Those capabilities provide an abstraction for text and HTML content which means most times there is no need to directly encode the raw email format which is defined in RFC 5322 formerly known as (RFC 822). But sometimes you may want to create more complex messages that have other Multipurpose Internet Mail Extensions (MIME) parts that are not directly exposed via the SparkPost’s RESTful interface.

Simplified Email Composition

First, let’s review a sunny day scenario for sending an email. Use the transmission endpoint to provide the text and HTML content. Behind the scenes, SparkPost takes care of composing a valid RFC 5322 email. SparkPost will insert substitution variables from substitution_data into the text and HTML content. This is a powerful way to generate custom content for each recipient in a common template.

Here is an example transmission with HTML and text content with substitution_data.


Substitute Arrays of Data 

Many folks realize that SparkPost’s transmission and template endpoints can do simple content substitution in email headers and email bodies. But many overlook the ability to provide conditional content or arrays of data that can be substituted as well. You can also provide unique content per recipient. In this example we send an array of unique links to each recipient.

This is accomplished by providing a JSON array of data that will be populated into the email body. Once the data is provided SparkPost will use logic in the template to populate it.

In this example SparkPost will look for substitution data called “files_html” and do a “for each” on each element in the array. It will create a row with the value of “file” in the “files_html” element. Note the triple curly around “loop_var.file“. This is because each element of the array contains HTML and we need to tell the server to use it as is and not escape it. The text part will be a simple text label and the URL to the file.

Here is the completed working example:

Pro Tip: In your code it is advisable to keep the view markup separate from the data but the goal here was to keep the example as simple and easy to follow as possible so we created two arrays. One array is for HTML part and the other is for the Text part. In production use it would be common to have one set of data and write the logic in the template code.

Attachments in Transmission Capabilities

The transmission endpoint also provides an abstraction for sending attachments. Below you will see attachments are specified in the content.attachments array where each object in the array describes an individual attachment item. Just as before SparkPost will take care of encoding text, HTML, substitutions and iterating through the attachment array to encode a properly formed email message.

Best practices dictate that sending attachments is best avoided unless explicitly required as part of your service.

name type
type The MIME type of the attachment
name The filename of the attachment
data Base64 encoded file data

This is what an attachment looks like inside transmission content stanza:

You can also send “inline images” in a transmission. These are very similar to attachments and are specified in the content.inline_images array where each of the inline_image objects are similar to the attachment object shown above.

Attachments in Templates

Now that we have the proper background for sending attachments with the transmission endpoint let’s take a look at how to do this with templates. At the time of this writing, there is no attachments abstraction like you find for inline transmissions. One might conclude that templates can’t be created with attachments. You would be partially correct but there is a work around, although you will no longer be isolated from the RFC 5322 format.

You can accomplish attachments in templates by encoding RFC 5322 content yourself which includes the attachments. The good news is you won’t lose the ability to still use Substitution Data in your email headers, HTML and text parts. Be aware that this type of template limits the substitutions to the headers and the first HTML and first text part.

Here is an example of how it is done.

RFC822 Email

Create your RFC 5322 email with the substitution data you want. I created this one in my mail client and sent it to myself. Once I received it I copied the source and replace the fields I want to dynamically substitute.

The last MIME part in this message you will see Content-Disposition: attachment; filename=myfile.txt”. That is where the name of the file is defined. Your attachment content will most certainly be much more complex but this example is trying to keep it simple.

Stored Template

Once you have a valid RFC 5322 email store it using the email_rfc822 form of the template endpoint instead of using text and HTML fields. Here is an example of what the content looks like for that message:

When the request completes, SparkPost will respond with a unique identifier for your new template. For example xxxxxxx.

Sending the Template

The good news is that creating the RFC 5322 content was the hard part. From here on out sending that template with SparkPost is exactly the same as sending any other template.

Here is how we send that template and populate the substitution data:

Templates from a Mail Client’s API

If you are using a programming language that has a library for composing an email, you can use that to programmatically create the template or even send the message inline. Here is an example of using JavaMail to do that very thing through SparkPost’s transmission endpoint. This method should be easily translated to PHP or your language of choice.


Now that you see how SparkPost can be used to send email of almost any complexity you may want to have a look at “SparkPost Supports Sending Email on Apple Watch” or have a look at the substitution syntax to see how it can be used with “if then else”, “expressions in conditionals” or “array Iteration” right inside your template or transmission content.

This blog post was inspired by a question from one our of our fantastic community members who went on to write the SparkPost C Sharp library. If you want to get deeper with SparkPost, I encourage you to join the conversation in the SparkPost Community Slack Channel. You can also connect with us through the SparkPost development hub and on Twitter.


If you liked this post, be sure to check out Automatic CSS Inlining with SparkPost

We’re adding some great features to help developers looking for a Mandrill alternative. Spoiler: subaccounts are here.

orange we heart developers banner twitter awards

** 3/31/2016 – Update: Subaccounts are now live! Further detail here.

A Feedback Frenzy: How You’re Helping to Make SparkPost Better

Wow. It’s been an amazing month of hard work for the product team here at SparkPost. And I know I’m not the only one keeping my caffeinated drink of choice flowing (through an IV drip, if necessary. Diet Coke girl, here BTW).

We’ve always worked to make SparkPost the most awesome email delivery service, period. And we hear from developers and other customers with product feedback pretty often. But, in the wake of MailChimp’s decision to stop offering their Mandrill product as a stand-alone offering (and endorsing SparkPost as a Mandrill alternative for developers), our Twitter and community Slack channels have been flooded with feedback, feature requests, praise, and yes, even constructive criticism. And we’ve tracked, discussed, and prioritized every single one. In fact, if you’ve given us product feedback, you’re likely to have seen one of our product managers or engineers reach back out for additional insight on the pains, challenges, and use cases you’re trying to solve.

This type and volume of feedback is every product manager’s dream come true, and I want you to know that we’re giving your feedback the care and attention it deserves. That’s just how we work. For over 15 years, our team has lived and breathed the belief that partnering with our customers to drive innovation and excellence in messaging is the right thing to do.

Now, that’s not to say we’re going to implement every feature or make every change that’s asked of us. A big part of my job is to take a hard look at requests to ensure they:

  • Help developers integrate our service easily… and make it possible to really innovate with email;
  • Meet the functional needs of the current and future markets we serve; and
  • Are aligned with our goals and values as a company, as well as the best practices in the email and tech industries.

This perfect storm of feedback could have become really overwhelming, really quickly. Fortunately, we’re big believers in agile development practices. And, as an agile company, leveraging a mix of Scrum and Kanban, we’re pretty darn good at knocking out small wins while also working to implement more complex or comprehensive improvements. We’re also huge fans of iterating on features—allowing our customers to get started using a feature, sooner rather than later. Once a feature or improvement is released, we capture feedback on how it works in the real world, and what could use a little tweaking, and continue to iterate from there.

As a product manager, It’s been gratifying to me to see how well the agile development practices really work, even (or perhaps especially!) at the pace that we’ve been working over this past month.

Here’s the New SparkPost Goodness

So: what have we done in the last couple of weeks? A lot! Without further ado, I’ll summarize some of new SparkPost highlights of the past month:

  • We got the pricing right: Check out what we’re doing with SparkPost’s pricing
  • Test Mode: The ability to test your integration before moving it to production, without the fear of sending to real live customers! We’ve also heard requests to support test-only API keys and webhooks—it’s definitely on our radar. Learn more about SparkPost’s new test mode.
  • CSS Inliner: To ensure that your email looks the same across the wide proliferation of inboxes (particularly with the…quirks… of Gmail), it’s a good practice to inline your CSS by removing it from a <style> block and putting it directly into each HTML attribute. That can be extremely painful and honestly, ain’t nobody got time for that. Put some fun back in your day and let us handle this task for you. Learn more about CSS inlining with SparkPost.
  • Mandrill Template Converter: Our template guru Ewan Dennis recently wrote some preliminary tips for manually translating Mandrill templates for SparkPost. Now, he’s working on an automated tool to make it even easier. The tool is still in… let’s call it beta, but if you want early access (and are willing to do some real-world testing), he’d love to have you. Join the SparkPost community Slack and ask for @edennis. He’ll give you the good stuff. **Update: the Mandrill-to-SparkPost template tool is live! Check out Ewan’s latest post about where to get it and how to use the tool to convert and migrate your Mandrill templates.
  • WordPress Plugin: We’re continuing to evolve this plugin by adding support for API over SMTP for people that are blocked for ports 587/2525, template selection, and to allow tracking to be toggled on/off from the plugin. Have more ideas? Please share them! Learn more about SparkPost’s WordPress plugin.
  • C# Client Lib: This one makes our heart swell because it came from a community member! Thank you thank you! Check out the community-developed SparkPost C# library.
  • Run SparkPost in Postman: SparkPost is an API-first service, because we love developers. And because it’s the best way to innovate with email. It’s that simple. What this means in practice is that we build our APIs (you guessed it) first, and then build our UI using those same API calls. Having said that, we also love our UI, and there are plenty of SparkPost users who’d rather not use a cURL command line or dig into the details of HTTP to build their API requests. This is where Postman comes in, turning an API request and response into something much more human-readable. Learn more about running SparkPost in Postman.
  • Slack community: where our teams are available for real time feedback on integration support, best practices, and developer love. Also? We’ve just uploaded all of our favorite emojis. It’s amazing what a little :homerbush: can do for your mood. Join the SparkPost community Slack team.

Oh, and One More Thing: Subaccounts! 

Of all the requests we’ve received over the last several weeks, by far the one raised most frequently is for “Subaccounts.” Fortunately, we were already well underway in terms of R&D for this feature, and we were able to shift some other priorities around in order to focus on bringing this to market ahead of the Mandrill cutover on April 27.

Before getting into any of the details, let me answer the most frequent one: “When?”

** 3/31/2016 – Update: Subaccounts are live! This initial launch will be closely followed with additional feature updates throughout the month of April, with all of the core components in place by the week of April 20. We know that this timing will make it tight for some customers who currently rely on Mandrill’s subaccount features. So, here’s what we’re doing:

  • We’ve already updated the API and SMTP documentation to include the subaccounts components, so you can start preparing immediately. The subaccounts API and SMTP documentation lives in our Developer Hub.
  • A comprehensive knowledge base article will be available within a few days that will outline use cases, implementation specifics, how-to’s,; and a host of future enhancements we’re already focused on.
  • Our awesome team is available on Slack to help answer any integration questions you may have.

What all of this means is that you don’t need to wait for the Mandrill cut-off date to get started with your migration. You can open a SparkPost account now, begin your integration, and familiarize yourself with the features and resources that are already available. By following these steps you can be up and running with subaccounts prior to the April 27 Mandrill cut-off date.

Some more details on subaccounts:

  • Subaccounts will be available on all pricing plans, including free. There will be no additional charge associated with subaccounts.
  • Both the UI and our APIs have support for subaccounts features, though some areas of the UI and API will not be supported fully at launch.
  • The first launch in early April will provide subaccount support for the following features:
    • Metrics API (Not available for subaccount API keys)
    • Message Events API
    • Sending Domains API
    • Tracking Domains API
    • Suppression List API
    • SMTP API
  • Following closely behind the initial launch (but before the Mandrill cut-over) will be subaccount support for:
    • Transmission API
    • Custom Tracking Domains
    • And more!

In addition to subaccounts, we’re actively underway with providing customers the ability to have multiple dedicated IPs per account, as well as the ability to manage those IPs for your subaccounts. More to come on those items in the next couple weeks as well.

Thank You, and Please Keep Your Feedback Coming! 

I want to acknowledge personally how valuable the feedback of our growing developer community has been in helping us to prioritize and accelerate many of these new SparkPost features.

To everyone who has taken the time to reach out to us, please accept my genuine thanks and appreciation. It’s people like you, sharing the good and the bad, that are helping us make SparkPost an even more amazing service for everyone. You rock. I’m reminded every day why I love the developer community.

If you haven’t joined in the conversation yet, please do! I’d love to hear from you on Twitter @AmieDurr. And now, you also can find me in our community slack.

-Amie Durr
VP Product Management

** 3/31/2016 – Update: Subaccounts now live! Further detail can be found here.

Biz Eval Guide Blog Footer

One of the great perks of attending Insight, SparkPost’s annual user conference, is sharing best practices and learning from the expertise of the pros who build, manage, and use next-generation email infrastructure on a large scale. No small part of that is the hands-on sessions led by members of our product team and longtime expert customers who know how to make the SparkPost platform sing.

Three of these technical boot camp sessions dug into powerful SparkPost features: finely-grained tracking of user engagement, the rich capabilities of advanced templates, and the intelligent business logic of multi-channel email, SMS messaging, and app push notifications. Though nothing beats being there for the technical deep dives, here’s a chance for the next-best thing: notes from the sessions and the boot camp leaders’ presentations. Dig in, and enjoy!

First off the blocks was “Using the Engagement Tracking and Metrics APIs to Bring Insights to Your Business.” This informative session examined the ways SparkPost allows senders to get the most from the fine-grained information about customer behavior and interactions with messages. Engineer Steve Tuck demonstrated using SparkPost’s web user interface for interactive queries, APIs for pulling data into external systems, and Webhooks for streaming events data in real-time.

Insight User Conference Bootcamp – Use the Engagement Tracking and Metrics APIs to Bring Insights to Your Business from SparkPost

Next up, SparkPost’s Fiona Snoddy and Isaac Kim used “Advanced Templatization” to demonstrate how to use the powerful templating features of our service. SparkPost templates can incorporate substitution data, conditional statements, looping flow controls, and dynamic content pulled from other systems. Together, these features enable a sender to personalize text, optimize offers, or deploy other business logic.

Insight User Conference Bootcamp – Advanced Templatization from SparkPost

One final bootcamp discussed how to incorporate “Multi-Channel Messaging with SparkPost Elite.” Using one platform and set of APIs to generate email, SMS, and push notifications means it’s possible to send a customer the right message at the right place at the right time, whatever the medium. SparkPost’s Ewan Dennis and Bruce Nowjack teamed up to give a really compelling demonstration of building a multi-channel app in real-time.

Insight User Conference Bootcamp – Multi-Channel with SparkPost Elite from SparkPost

If these power features make you want to learn more, it’s easy to get started with SparkPost. And if you’re a developer looking to get your hands in some code, the SparkPost Developer Hub is a great place to begin.