Today, I thought I would point out a few of my favorite tricks when creating templates. Let’s call them email template hacks. I’ve briefly mentioned some of these in previous blogs, so today I’ll expand on those ideas and add in some use cases and examples.

1. Leveraging Substitution Fields in CSS

The first trick is to use substitution fields for your CSS values. Colors, fonts, height, pretty much anything can be substituted. Many email clients leverage header styles while others don’t. However you choose to tackle formatting your emails across various clients, you can leverage substitutions both inline, in the header block or both.

There are a few different approaches available if you want to inject CSS in the header block in order to maintain standards through all of your templates. The first method is to simply replace CSS values with substitution data. For example, if modifying the text color for an html <a> tag within the <style> block I would modify the color field to reference a substitution field. Here’s an example:

Then, in the transformations JSON call, I would have the corresponding substitution field:

This is the easiest way to modify the look and feel without having to rummage through hundreds of template and make changes. This also assumes that you are holding those values somewhere on your server and can retrieve them fairly easily for the transmission JSON creation.

Building this example up, you may use a dynamic_html and/or dynamic_text blocks. This allows you to make wholesale changes by bringing in large CSS blocks that you may be storing in a repository of standards. Change the blocks in that repository, and you change all of the templates that get the dynamic html/text referenced.

Please keep in mind that dynamic_html/text blocks are held within the global substitution_data blocks, now the recipient substitution_data blocks. A CSS block within the Transmissions dynamic_html structure may look something like this:

This code block is no different than if you had it placed in the HTML template itself. Now it’s just easier to update when referenced into the template via the transmission which pulls from a central repository. The template itself will use this code block with the following entry in the template somewhere in the html <header> block:

If you want to go all out, dynamic rendering even allows for recursive substitution fields. This means that the dynamic code block can have substitution fields as well. A good use case for this is when you OEM or White label your product. In the following example, the CSS block is similar to the one above, but there are substitution fields for the CSS values. Those substitution fields are then placed in the global substitution block of the transmission. For example:

But wait, what if I want to use inline CSS, you ask? Well, just change those big blocks of CSS settings and make them substitution fields.

2. Not sending the email at all if certain data does not exist

As emails become more personalized, they start to look and feel like transactional emails. This is a great trend, but it opens up a greater possibility for unfinished emails. Let’s say a job board sends lists of job opportunities to all active members each morning. Hopefully there are checks and balances that stop the application from requesting for an email to go out if there are no matches for that user, but as a template designer, I don’t want to rely on that. So a little trick that I use is to check for a specific substitution field or array that must be present; if it doesn’t exist, I call a non-existent function with the following line somewhere in the template (I tend to put this on the bottom). This will automatically kill that email from being generated so the bad email doesn’t make it out the door. In the example below, I’m checking for the ProductList array, and if it doesn’t exist, I call the function ‘crash’ with the parameter ‘onpurpose’.

3. Validating data before creating the table for arrays

SparkPost has a very powerful feature that allows a template to loop through an array in order to display a set of information, like jobs, real estate listings or products. In fact, SparkPost even supports having loops within loops within loops. Often, multiple tables, rows and columns get created order to display this information in the fashion the content creator wishes. But what if there is no data to show in one of those loops, but you still want the email to go out, just without the empty rows or tables? In many of my retail templates, I display a list of products that have ‘x’ number of features for each product. If there are no features, I still want the product to be displayed but I may not need to create some of the corresponding html code for the empty features list. In order to keep the email looking good, I check both the existence and the value of my arrays before building unnecessary tables, rows or columns that would house this information. This trick is solved with a simple two part if statement:

4. Using substitution fields in the subject line

So you built your template and placed it onto the SparkPost server. Don’t forget to create a dynamic subject line. One of the easiest way’s to get your email clipped by Gmail or buried into a huge thread is to use the same subject line over and over. So go ahead and use substitution fields for your subject. I often put the person’s name, along with a subject field. My Subject field in the SparkPost UI is set to something like:

5. Use dynamic_html for headers and footers

So, continuing on the theme of standards, I like to send my headers and footers to each template via the Transmission API in the form of a dynamic_html entry. This allows me to keep a library of headers and footers that can be easily modified without having to change every template. Because SparkPost doesn’t have the ability to store those headers and footers on the server then insert them into the targeted template, it’s a good practice to have those standard headers and footers in another content management system that marketing can change without developments help. When the transmission json is getting built, the appropriate headers and footers are placed into the dynamic_html section which is then pulled into the template before sending.

Upcoming Email Template Hacks

So those are some of my favorite template tricks. In my next blog, I’m going to tackle the trick of validating that the transmission payload has all of the data the template is expecting to receive. The blog will be accompanied by a full PHP code sample for this validation step.

Happy Sending

Jeff Goldstein
Senior Messaging Engineer

Any email template hacks we missed? Tweet us or come find us in our community Slack

10 Steps Great Deliverability Blog Footer

Making your retail email template library work smarter, not harder

The curse of the retail email template! Should you display 10 products using 5 rows of 2? Or 9 products using 3 rows of 3? Perhaps 10 rows with each product on it’s own? For most companies, testing which email structure works best is a royal pain. Well, I’m here to explain how one SparkPost template can support any combination of rows and columns for any retail email template and beyond.

retail email template rows and columns

The ability to apply any row/column combination using one template is achieved by the combination of a flexible data-driven template with the structure of the data being sent to the template. When using SparkPost’s Transmission RESTful API, your application will determine the look of the email by changing how it organizes the product information it sends to the template. To consume the data properly, SparkPost’s conditional loop statement, each, is used within the template. In this example, the each statement is needed twice; one nested in the loop of the other. The outer each represents rows while the inner use of the each loop will drive the number of columns, using products from our JSON, for each individual row.

Before reviewing the template code/HTML, let’s look at some sample input data. Shown below is a JSON structure that holds the product data for 4 rows with each row having product data for any number of products. This product data would be placed in each substitution_data stanza for each user.

The data above represents 4 rows of products with rows 1, 2 and 4 having two products and row 3 having one product.

In JSON speak, we have two arrays of data, rows and products. The template will loop through each array depth-first until it has processed all of the rows of data. To change what the email output looks like, simply change the structure of your data – how many rows there are total and how many products there are for each row. This means you theoretically have an unlimited number of ways to represent your data, all using one template.

The above sample is actually a fairly simple example where we are only sending the image URL, the price and a (sub)title for the picture. What if each product had a set of features to display, or maybe product categories as well. In the real world there may be a landing page URL, title and subtitles, discount prices and a host of other bits of information. I only bring this up in order to demonstrate that SparkPost’s templates can handle any depth of JSON arrays. Here is a sample of what one of the product structures might look like if it had a set of features:

Now let’s examine the template code that will loop through the above data producing 4 rows showing 7 products.

[Note: In this example, I’m creating a new table for each row. This isn’t mandatory, it’s just the approach that I’ve taken for this example.]

Here is the output:

retail email template output images

The magic starts on row 8 with the first each statement which represent each row of products. Then, on row 14 we have the second each statement that will loop through all of the products for a row. The rest of the code is just table, row and column tags along with a few lines to actually display the images, titles and price.

A more advanced example

Now let’s take this to another level – hey this is an advanced topic after all! I am going to demonstrate how to minimize the size of the JSON structure and the data sent from your application to SparkPost. For a simple use case, what if we want to offer the exact same products to a second user but without row 3? That means we have to send all of that data again minus the data that represents row 3. When you are sending hundreds or thousands of emails, the amount of data may not seem like much. However, when you’re sending millions or billions of emails, the savings in time and bandwidth can be significant.

We can minimize the amount of data to be transferred by moving the product details out of the individual user’s substitution_data and placing it into a global array that is available to each user within a Transmission API call. In order to get the best throughput out of SparkPost and be most efficient with data transfer, SparkPost suggests that large bulk mailings be grouped into multiple Transmissions calls, each containing anywhere between 5,000 – 10,000 users. That not only increases throughput due to reduced connection setup overhead, but it also lowers the risk of connection issues since you will cut down the number of connections by 4 orders of magnitude. SparkPost can handle individual calls at that scale with high throughput, but consolidation of transmission calls does bump up the overall speed of message generation and delivery.

In order to use this approach, minor changes are necessary to both the JSON structure within the Transmission API call, and the HTML template.

Let’s look at the JSON data first. This example is going to be a little more detailed in order to show two unique emails being sent from the same Transmission API with the same product information.

The first step is to move the JSON data for each product to be displayed up into the global substitution_data section. The orange highlighted products key is the start of the product array. Unlike the product data that was placed in the recipient substitution_data from the first example, each set of product information now needs a unique key which is indicated by the green highlighted fields. The products array is different from a typical JSON array. Notice that there is NOT a set of square brackets, [], surrounding the products. Taking this approach allows us to go directly to each product data set without knowing where they are in the products array. If you look at the substitution_data  at the individual recipient level, which are denoted by the aqua highlights, you will see a familiar row/product structure from the last example. The difference this time is that instead of the product details, the recipient substitution_data fields only have an id field. That is our link back to the detailed product information within the global substitution_data  set and drives which products will be shown for each user. If you look at both recipient users, they both have different sets of products to display and each has a different format. The first recipient is using the same 4-row format of the first example, while the second recipient will get two rows of products, 1 in the first row, and 3 in the second row.

The only changes that we need to make in the template is how we reference the field(s) we want to display.  The first part of our reference is to the products array.  Next we index to the id that we are interested in, then the field name itself.  So to use the product_url, we have:


(Note: Please refer to the SparkPost documentation to further understand how to use arrays and the loop_var keyword)

Here is the full html template code:

So that’s it. By creating a two level array of rows and columns, along with some of the other topics discussed in previous blog posts, any company can dramatically consolidate their retail email template library while simultaneously increasing flexibility and customization.

Happy Sending,

Jeff Goldstein

Questions around these retail email template examples? Or email templates in general? Drop us a line below, on our community slack or Twitter.

White Labeling Email Communications with Template Substitutions

In past discussions, we have talked about how substitution can be used to create dynamic emails. This drastically decreases the number of templates that need to be managed by using conditionals and looping statements. But did you know that you can also use substitution for your CSS within an email?

For companies hosting email services and providing sample templates to their customers, this capability can significantly decrease the number of email templates needed. In order to illustrate the challenges and how template substitutions can solve many of those issues, let’s create a fictional ISP who is bringing on a new customer.

A Practical Application

So, let’s imagine a fictional ISP named SuperComm; they provide corporate phone and webinar services to their customers. Emails from SuperComm to their client’s employees (e.g. sign-ups, feature updates, and personalized notices) are all branded for that specific client using their own color scheme and logos. In this example, SuperComm just acquired Graphite550 as a client and now needs to start the process of helping Graphite550 to get their employees to use the SuperComm platform. In order to do this, SuperComm’s Account Managers obtain the following information from Graphite550:

  • Color scheme: white and orange
  • Copy of Graphite550’s logo
  • Graphite550 phone support numbers
  • Graphite550 support website URL
  • Address
  • Corporate URL

Once they have this information, the account manager goes into the SuperComm repository and retrieves a copy of the 15 default emails that are used for each SuperComm customer. They then spend the next several hours branding each of these email templates with Graphite550’s information. As you can imagine, this is a very error prone process which typically needs a few iterations and the eye of a few different employees to get right. Once finished, SuperComm then needs to keep each of these templates in a repository along with all of their other 700 customers. While SuperComm has done everything they can to minimize changes by separating out the main body from headers or footers, maintaining over a thousand templates is very challenging.

So for this example, let’s take a look at the welcome email that will go out to each Graphite550 employee.

Just this one email has over 20 different fields that SuperComm uses in order to brand the email to Graphite550, which turns out to be over 65 individual replacements that have to be done by the account manager. If the other 14 templates are similar to this one, that means there are close to 1000 changes that need to be made for each customer!

So how can this be simplified? SparkPost has the capability to not only support recipient-focused personalization like ‘first_name’ and ‘accountid’ but also CSS entries, enabling per-customer white labeling. In the above example, the title line actually looks like this in the template:

Not only is the company name a substitution field, but so is the background color and the text color which are passed to SparkPost along with the employee personalization. Here is the global substitution data for Graphite550:

Note: In our example, we are using inline CSS but those CSS fields could also be placed in the header, as in this example:

In this new approach all the account manager needs to do is to put this data into a simple web form. This form, created by their IT department, obtains the necessary data, generates a preview for confirmation, and places it into a database. With this new process, the application triggering the welcome emails to each new customer will not only obtain the personalization fields like first name, but also the branding fields. Both types of information are then sent to SparkPost so the email can be branded and personalized during the generation process.

By using branding substitution fields within each template, SuperComm can clean out their repository of 1000+ branded templates down to the original 15 that can be used for every one of their customers. As a result of this, customer acquisition costs decrease significantly and template management becomes simpler.

Now that you know this, the next question is, how can substitution simplify your life?

Happy Sending,
Jeff Goldstein

Please feel free to leave any questions about template substitutions or white labeling in the comments.

Top 10 Blogs: Our Year in Review

We’re finishing out the year with a roundup of our top 10 blogs from 2016. The Mandrill announcement in April impacted our community, and as a result our blog, in a big way. We’re recapping that along with other top posts on deliverability tips and email marketing best practices down below. As always, our ears are open, so if there’s a certain topic you’d like to see on the blog, leave us a comment, tweet us, or ping us in slack.

Without further ado, we give you the top 10 blogs of 2016:

#1 Mandrill Alternatives

It’s no surprise that our Mandrill alternative blogs dominated our top 10 list (5 out of our top 10). We responded in real-time to the Mandrill crisis, and our CEO even weighed in and made you a promise he intends to stick by for the long haul. The Mandrill incident also inspired us to create SendGrid and Mailgun migration guides, check them out when you have a chance.

Mandrill Template Migration top 10 blogs

#2 PHP

But beyond Mandrill, we also had some other top posts. Coming in second was using SparkPost in PHP. Believe it or not, many of you use PHP through our WordPress plugin.

PHP in SparkPost

#3 Advanced Email Templates

For developers who want to get the most out of SparkPost templating capabilities, this post was meant for you! In this straight-forward post, Chris Wilson makes sending email easy and gives you some pro tips along the way.


advanced email templates


#4 What Recruiters Look for in a Dev Candidate

Everyone wants to know how to interview well. In this post we told you about what four tech recruiters look for when hiring developer and engineering candidates.

Recruiter for Dev Candidate

#5 Webhooks!

One of the most useful elements of SparkPost are our webhooks and in this post, Ewan Dennis walks you through the basics and beyond. Knowing what to expect functionally beyond the raw API spec is half the battle when consuming new data sources like SparkPost webhooks.

webhooks: beyond the basics

#6 Outlook and Hotmail Email Deliverability

The Outlook inbox is one of the major destinations for most email senders, especially those with large numbers of consumer subscribers. It also has a reputation for being somewhat tricky to get into. In this post, one of our deliverability experts, Tonya Gordon, shares what senders need to know in order to get the best Hotmail/Outlook deliverability and ensure their messages reach the inbox.

#7 Announcing Subaccounts!

Thanks to your feedback, the Mandrill event helped us expedite our release of subaccounts ahead of schedule. Our VP of Product told you about how we process your feedback and what’s available with subaccounts.

SparkPost #WeLoveDevelopers

#8 Are You an Email Rookie?

Sometimes you need to go beyond a top 10 list and in this case we did — 17 tips on how not to be labeled an email rookie. In this post we put together a list of common mistakes, with a heavy dose of snark, on how to avoid being labeled an email marketing rookie.

Email Marketing Rookie Kid Missing Steering Wheel

#9 Retail Marketing Stats You Need to Know

Do you know what the lowest e-commerce order generators are? In this post, we give you five tips and stats for mastering retail marketing. From social media, to mobile and beacon triggered emails.

Retail Marketing statistics mobile 2016

#10 Setting Up SparkPost as your SMTP Relay

You know you need to send email, but you don’t want to spend a lot of time or effort on it — you just want something that works out of the box. It’s not too much to ask! Many frameworks, languages, and tools come with SMTP support, but the last step is the most important – an SMTP server. In this post, we walk you through how to set up SparkPost as your SMTP Relay.

And that rounds out our Top 10 Blogs for 2016! Any industry trends or topics you think were under-represented? Leave us a comment below, or tweet us!


Email Templates

Why Shifting from Internal Template Generators to Newer Platforms Makes Sense

Everyone has an opinion on how to build the best ’email templates’ that capture a customer’s attention and leads them to a call-to-action. Some leverage great graphics. Others use captions like, “The 10 Best Mistakes That Cost You Millions of Dollars That You Will Do Again!”

What’s often neglected is ‘how’ to build these email templates in a flexible manner that supports the dynamic needs that drive today’s complex business. At SparkPost, we have found that most companies moving from either an on-premises MTA or a self-service cloud ESP were forced to build their own template generators. Some are fairly sophisticated and flexible with a UI. Most, however, are complex pieces of code that build the email through a series of conditionals and saved text.

Over time, these applications have become fragile systems so changes or upgrades are rare, if any. Even simple changes to text within an invoice email can take weeks given the backlog of work development already has. Plus, they need to test it to make sure they’re not introducing further bugs.

With this in mind, I’m writing this blog, and eventually a series of blogs, to help our SparkPost customers see a vision of how they can move from these older systems and leverage the SparkPost templating system such as:

  1. Why making the shift from internal email generation systems to newer platforms makes sense
  2. The simple stuff, moving from SMTP and fully built emails compiled by development
  3. White labeling email templates; Using substitutions to modify look and feel of the HTML output for branding and white labeling
  4. Shared or Global data versus Recipient data
  5. Arrays and how to leverage them
  6. Dynamic output with multiple rows and columns of data
  7. Multi-language support

Many customers write their own templating system out of necessity. And since most are code-rich and depend on development to make the simplest of changes, Marketing gets hamstrung in their ability to keep up with the demands of a rapidly changing world. Because of this demand for change, when possible, it’s better to separate Marketing Design from Development; this is the key factor for moving to templating for many customers. This doesn’t mean that development won’t help build or customize some of the email templates. It just means that much of the work they were doing is minimized. In a perfect world, development worries about obtaining the right data that goes into the message. And marketing worries about the aesthetics and wording of the message.
In the long run, the speed of change that takes place by separating the creative from development is well worth the change.

Now that development doesn’t need to worry about the creative, they can simply focus on three things:

  1. What data to send each customer,
  2. What events trigger sending the content, and of course,
  3. Any segmentation to target the right users during larger blasts such as newsletters.

Another benefit of separating the creative from development is that pulling the data for each user becomes simpler. The need for conditional after conditional to get the proper data for a given template can be simplified to gather all the data for a user, then letting the template decide which data to use. If the template doesn’t use the data, we only lose the cost of transmitting it from the back end server to the SparkPost platform. However, don’t take this approach to the extreme by sending obnoxious amounts of unused data. Typically, there’s a bulk of personalized information that one can gather and send as a standard bit of personalization data for a template to use. Now, Marketing and Development can synchronize on what data will be available. Then, Marketing can ensure it’s used properly and presents itself in a manner fitting to their banding and messaging.

Now that we have a business case of why to shift from internally built email generation systems to newer platforms that separate out development from the creative, we’re ready for our next blog post. In the next one, I’ll discuss gathering the data necessary for substitution and moving away from fully built out emails sent via SMTP.

Happy Sending,

Jeff Goldstein
Sr. Messaging Engineer, SparkPost
Some Sample Email Templates

10 Steps Great Deliverability 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 “” 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


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 are excited to announce the availability of Momentum 4, the latest breakthrough in digital messaging technology.  With this latest release of our flagship messaging platform, Message Systems further cements its lead as the industry-leader in digital messaging.  These new capabilities in Momentum 4.0 will further enhance our customers’ email programs and drive even better customer engagement.

“With the release of Momentum 4, Message Systems is keeping its edge as the top-tier platform for enterprise-class senders,” said Jack Hogan, chief technology officer at Lifescript. “The analytical and data integration capabilities in the new platform will help email senders become more effective than ever before in creating compelling campaigns, reaching the inbox and engaging customers.”

The new features in Momentum 4 now provide real-time access to messaging and engagement data, new message generation and templating capabilities and new cloud-enabled APIs. Here’s what you can expect when you upgrade to Momentum 4.

1. Critical messaging and engagement data

  • Email analytics Momentum’s revamped architecture now allows for real-time capture and reporting of messaging events as they happen – from message transmission to customer conversion.
  • New user interface (UI) – With the new user interface, customers will be able to easily discern the success of transmissions and campaigns and quickly identify potential delivery problems or performance issues for resolution.


2. New message generation and templating capabilities

  • Message Generation: Lists, content and templates can be brought together to generate messages within the Momentum 4 platform to enable high-volume campaign-driven messages, as well as transactional messages, all in one unified messaging solution.
  • Template Management: Powerful, but easy-to-use template management allows data to be incorporated from external business intelligence solutions and other sources, as well as supports both in-line and stored templates.

3. New cloud-enabled APIs

  • Enhanced APIs: As the industry’s most extensible email software, Momentum 4 supports many new application programming interfaces, including new Injection APIs, Stored Template APIs and Aggregate Reporting APIs.
  • Industry Leading Performance: All new enhancements fully embrace Supercharger, allowing for unparalleled server density and messaging logic complexity.

The release of Momentum 4 further cements Message System’s position as the industry leader of digital messaging by turbocharging performance and helping customers to identify and quickly resolve issues in real-time. If you are interested in learning more about Momentum, we’ve got you covered. Read the full press release for more details or register for an online group training session by Message Systems University – Introduction to Momentum 4 for Senders.


Message Systems solutions power a global network of the largest, most complex messaging operations, such as Internet businesses Facebook, LinkedIn and Twitter, and top email marketing companies like Yesmail and Marketo, which collectively send over 2.5 trillion messages a year — 20% of the world’s legitimate email. Find out why these top senders choose Momentum in the What Sets Momentum Apart white paper.

What Sets Momentum Apart