Leveraging Substitution Data and Templates to Personalize Emails

Jeff Goldstein
Jan. 30, 2017 by Jeff Goldstein

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

screen-shot-2016-10-31-at-2-59-57-pm

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.

screen-shot-2016-10-31-at-3-00-40-pm

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

3 Comments

  • Please put up more examples of substitution data from arrays in node environment with javascript (angular). I have substitution data working for all elements but passing array and have gone over and over your developer docs.

  • Hi Gabrielle,

    Thanks for your suggestion, we will pass this along to Jeff and incorporate more examples of substitution data in future posts.

    Jen

  • Hi Gabrielle, I think this more recent blog post answers your question: https://www.sparkpost.com/blog/consolidate-retail-email-template/.

    If I’m wrong, please let me know. I also have many template examples using arrays. You can find some in a github repository at: https://github.com/jeff-goldstein/sparkpost/tree/master/Templates

    Regards,
    Jeff

Related Content

Email Templates: Separating Marketing from Development

Sr. Messaging Engineer, Jeff Goldstein, shares why our customers should move from internal email generation systems and leverage SparkPost's templating systems.

read more

Anatomy of a Great Email Template

A great email template is the skeleton that gives you the structure you need to focus on what matters. Here are the must-haves for any email template.

read more

Advanced Email Templates

For the developer who wants to get the most out of SparkPost's email template capabilities, here's a guide to creating templates for more complex messages.

read more

Start sending email in minutes!

The world’s most powerful email delivery solution is now yours in a developer-friendly, quick to set up cloud service. Open a SparkPost account today and get started for free.

Get Started

Send this to a friend