SparkPost: Dynamic subject lines in email templates

Moving to Mandrill to SparkPost this week? (A lot of us are thanks to this.)

In Mandrill (and possibly other transactional email services) we can use the API to send emails using templates. We send a bunch of information including recipients, content, metadata, and subject, ad we let ‘er fly. Boom, done.

For the most part, I’ve found SparkPost to be pretty similar, except on one point: subject lines. Specifically for emails sent using templates. When you’re using a template, several options in your API call get ignored, including “subject”. It defaults to whatever you set when you created the template in the SparkPost UI. (It’s a required field.)

Worse, at the time of this writing anyway, there’s no clear way to fix it. It isn’t specifically covered in the documentation, and the support center answers (such as this one) are… not ideally helpful, we’ll say that.

But there’s good news. After losing a fair number of hours and hitpoints on this, I found out that…

It’s actually pretty simple

With SparkPost templates, we fill our template placeholders (name, content, etc) with curly-bracketed variables such as:

{{name}}

(Details on this are in their docs over here.) That’s what we put in the template to specify that this is the placeholder for the ‘name’ field in the substitutionData JSON array we’re sending them. Here’s a simple example of that part of our API call: (Also called a “transmission” in SparkPost world.)

{
   "substitutionData": {
      "name": "Tester Gunderson",
      "astrological_sign": "Quagmire",
      "favorite_color": "blue",
      "main_email_body": "This message is to transactionally confirm that your sign is 'Quagmire' (we didn't know that was a thing) and your favorite color is 'blue'."	
   }
}

Throw a key in there for Subject

With the rest of your substitutionData, add your desired subject line:

"subject": "We're sending this email to blue-loving Quagmires"

And then in the SparkPost UI, edit your template and change the subject line to {{subject}}. (Or whatever you want to name the variable.)

And you’re done.

Well, maybe. It depends on your use case. If you want to add dynamic variables to the subject line (like the recipient’s first name) you have another battle ahead of you. Hopefully, as more of us former Mandrill users migrate over certain questions can be answered more clearly than they are as of the time I’m writing this. (April 19 2016)

Good luck out there!