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

Malware Email AttachmentsI recently was catching up on my email, and I was struck that there wasn’t a single marketing message with an attachment in my inbox. The only notes with attachments were transactional in nature: a receipt from a store I made a purchase from and a voicemail notification from my company’s phone system. Those transactional messages didn’t have any images, nor were they long with a bunch of offers. Sure, there were a few links to their website where I could find marketing offers, but no big call to action beyond the essential transactional purpose of the message.

Now curious, I also took a look at my spam folder. In contrast, it had quite a few messages with attachments that looked to be marketing. Upon further investigation, though, it became very clear that those seeming marketing messages actually contained malware. Yikes.

Now you may think, how does this affect me? “The attachments I send aren’t malware, so what’s the problem?” Simple: you might be lumped in with the bad guys because receivers will judge you guilty by association. Anything you do that looks even slightly like the behavior of malware spammers will hurt your deliverability. In this post, I’ll look at some popular techniques used by these bad actors.


First and foremost, the bulk sending of non-transactional messages with attachments has become a clear indicator to ISPs that your messages have a high risk of being malware. It’s hard to understate what a significant problem computers infected with malware have become for ISPs. When a PC gets infected, it’s often used for sending more spam, which harms the ISP’s reputation, eats up bandwidth, and degrades their network for their customers. When an ISP permits marketing or other bulk senders to send attachments, they’re taking a very sizable risk of exacerbating this problem.

Forewarned and forearmed, I picked apart the header of a message that purported to be from a well-known sender, USAA. However, I immediately noticed a major red flag: a lack of authentication. SPF failed, and there was not a DKIM or Domain Key Signature. It is important to do both SPF and DKIM authentications in order to get into the inbox. ISPs have made it clear that without it, you’re fighting an uphill battle, and at high likelihood of being disposed of as spam.


SparkPost understands the importance of authentication and therefore signs with SPF and goes the extra step of signing with DKIM for the sending domain as well as the SparkPost domain.


Moving on from the message headers of this spoofed USAA message, I saw that this spammer was trying really hard to convince me to open the attachment. Sure, the imperfect grammar was a good warning that something wasn’t legit, but a recipient who is a USAA member, and perhaps not reading carefully, just might fall for it—and then, boom, the spammer’s mission is accomplished. Those of us in the business may be a little jaded, but if this technique weren’t effective, it wouldn’t still be around after all these years. It’s a major reason ISPs have become more and more strict about blocking bulk messages with attachments.


As we saw, the example malware spam above was sent in mass, without authentication, and with an attachment. To maximize deliverability legitimate senders should strive to look as different from that profile as possible. In most cases, it is far better to send an email with no attachment and instead include a link for your recipient to click to access the content you otherwise would have attached. But, if you do find yourself unavoidably in need of sending attachments there are a few key things to keep in mind:

  1. Don’t send attachments in bulk. Instead, send them only in response to transactions initiated by your subscriber. If a subscriber is expecting an email, they are more likely to locate the message and open it, even if it’s in the spam folder.
  2. Don’t include images or marketing-centric calls to action. It’s OK to reference offers and point them to your site, but be careful not to look like you are attempting to slide in the attachment with a marketing message.
  3. Don’t send apps or executable files, as they will be blocked instantly. There is a host of file types that are not allowed by ISPs. Do some advance testing to make sure what you are sending will be accepted by the ISPs you are sending to.
  4. Watch your grammar and spelling. Content is looked at very carefully when sending attachments.
  5. Authenticate! This is a best practice when sending any message, transactional or commercial.

Even when following these best practices, you may still find yourself in the spam folder. If that’s the case, it may be best to throw in the towel and try another approach—like using a file-hosting service to handle the attachment.