How To Validate The Data You’re Sending To Email Templates

Jeff Goldstein
Dec. 22, 2017 by Jeff Goldstein

I’m pleased to see a trend where SparkPost templates are getting more personalized for both transactional and non-transactional emails. This is excellent news for recipients because they get relevant content, and better news for the sender because customers are interacting with the email at higher rates.

Highly personalized email content means more relevant content for recipients and better engagement rates for email senders. A direct correlation to this personalization is that more substitution fields are being sent via the transmissions API (the SparkPost API used to submit email requests to the server) to the stored templates for merging. With more substitution fields, the backend application that calls the transmissions API needs to grab more and more data, creating a higher level of complexity between the template designer and the application developer. Ideally, the template designer is communicating what field changes are being made so that the application developer passes the correct information, but this isn’t always the case. The application developer can still read through the template to see what fields are necessary, but that can be a chore on large templates, especially if the application developer does not know when changes were made.

To simplify this process, I wrote a PHP library, TemplateToolsLibrary, to address this use case and a few others. Listed below is a summary of the library capabilities, which you can find in the Github repository master for your enjoyment.

Build Email Template Fields

Use Case: An application developer does not necessarily know what fields exist in a template so they want to generate a list of fields the template uses.

The library function BuildTemplateFields needs the following input fields and produces the following output:

Input

  1. apikey: This application uses your account to get the Template from your account. It needs an API key with the ability to read templates.
  2. apiroot: For SparkPost.com this should be: https://api.sparkpost.com/api/v1/
    For Enterprise customers, talk to your Technical Account Manager (TAM)
  3. template: The template ID you are scanning.
  4. templateItemList: An empty array that the library will fill with a list of all the fields found in the template.
  5. filename: This is an optional field that when present, the function will output the list of fields to that filename.

Output

  1. templateItemList: Is an array filled with the list of fields found in the template. Each field name is only listed once, and each fully qualified name is only shown in its atomic level.
  2. If the fifth parameter is present, the list of fields found in the template will be dumped into the filename passed to the function.

Caveat

This library function only displays the atomic name of a fully qualified component. For example, if the substitution data structure has an array called ‘ProductList’ which also contains an array called ‘FeatureList’, and each row within ‘FeatureList’ has a field named ‘description’ you have a fully qualified name of ProductList.FeatureList.description. But the library function BuildTemplateFields will break that down into three different entries, ProductList, FeatureList and description. While that does help the user see what all of the fields are, it does not show the structure of the array which will ultimately be needed in order to build the appropriate data structure. This nuance actually plays well for the library function SubDataCheck, but it does cause a little extra work for the application developer who is trying to understand the template enough to design the appropriate transmissions API call.

SubDataCheck

Use Case: An application developer has the challenge of pulling all of the substitution fields necessary for each template. At times, you want the application to validate that it has all of the data before sending the transmissions call.

Library function, SubDataCheck will do just that. Just like BuildTemplateFields, it will scan the template for each field name the template is expecting, but this time it will take any recipient and/or global data you send and crosscheck those fields with the fields within the template. This is a handy call just before you build the transmissions call in order to make sure that you have all the data you need. The function SubDataCheck needs the following input fields and produces the following output:

Input

  1. apikey: This application uses your account to get the Template from your account. It needs an API key with the ability to read templates.
  2. apiroot: For SparkPost.com this should be: https://api.sparkpost.com/api/v1/ For Enterprise customers, talk to your Technical Account Manager (TAM)
  3. template: The template ID of the template to be scanned.
  4. recsub: The recipient data you plan on sending to the template. While this can be an empty string if you have no data, the function is expecting a fully formed Json structure if there is data. This function is expecting the full substitution_data field that you would put into the transmissions call, along with {} around that data block in order to make it a Json structure ready to decode later in the process. For example:
  5. globalsub: The global data you plan on sending to the template. While this can be a empty string if you have no data, the function is expecting a fully formed Json structure if there is data. This function is expecting the full substitution_data field that you would put into the transmissions call, along with {} around that data block in order to make it a Json structure ready to decode later in the process.
  6. substitutionItemList: This is a pass by reference variable that is expected to be empty on the call. The library function will fill this with an array of unique fields names found in the combination of the recipient and global substitution_data blocks.
  7. templateItemList: This is a pass by reference variable that is expected to be empty on the call. The library function will fill this with an array of unique fields names found in the template.
  8. missingFields: This is a pass by reference variable that is expected to be empty on the call. The library function will fill this with an array of unique fields names found in the template but not found in the recipient or global substitution_data blocks.
  9. addEmptyFieldstoMissingListFlag: If you want empty/Null substitution fields to be added to the MissingFields list send TRUE; otherwise False.

Output

  1. substitutionItemList: The library function will fill this with an array of unique fields names found in the combination of the recipient and global substitution_data blocks. Each field name is only listed once, and each fully qualified name is only shown in its atomic level.
  2. templateItemList: The library function will fill this with an array of unique fields names found in the template. Each field name is only listed once, and each fully qualified name is only shown in its atomic level.
  3. missingFields: The library function will fill this with an array of unique fields names found in the template but not found in the recipient or global substitution_data blocks. Each field name is only listed once, and each fully qualified name is only shown in its atomic level.

Caveat

Like, BuildTemplateFields, this library function only displays the atomic name of a fully qualified component. For example, if the substitution data structure has an array called ‘ProductList’ which also contains an array called ‘FeatureList’, and each row within ‘FeatureList’ has a field named ‘description’ you have a fully qualified name of ProductList.FeatureList.description. But the library function BuildTemplateFields will break that down into three different entries, ProductList, FeatureList and description. While that does help the user see what all of the fields are, it does not show the structure of the array which will ultimately be needed in order to build the appropriate data structure.

This nuance actually plays well for the library function SubDataCheck because most references within the template will boil down to the atomic names. Using ProductList.FeatureList.description as an example, the template will probably have two substitution loop commands, {{each ProductList}} and {{each FeatureList}}. Even if there is a command of {{each ProductList.FeatureList}} that command will be broken down into two names, ProductList and FeatureList which will then be compared to the field names ProductList and FeatureList within the substitution data.

Those are the main two library functions, SubDataCheck and BuildTemplateFields, now I’ll review a few other capabilities that are available in the library.

isJson

Use Case: The application developer needs to check if the recipient or global data that is about to be passed to SubDataCheck is proper JSON. Since the email api, transmissions, expects a json structure, this function is a quick way to check if the recipient or global data that you are about to pass to SubDataCheck are proper Json structures. The proper format for the transmissions api is: {‘substitution_data’ : {fields………arrays……etc}}.

All you need to do is pass the substitution_data string(s) to the function and check the return string. If all is good, you will see a string “No errors’; otherwise, you will see text that will describe the error found.

GetTemplate

Use Case: Many SparkPost customers build internal tools that show what the template will look like and/or allow a user to edit the template.

This function will retrieve the full HTML code base for display, editing or scanning.

Input

  1. apikey: This application uses your account to get the Template from your account. It needs an API key with the ability to read templates.
  2. apiroot: For SparkPost.com this should be: https://api.sparkpost.com/api/v1/ For Enterprise customers, talk to your Technical Account Manager (TAM)
  3. template: The template ID of the template to be scanned.
  4. storedRawTemplate: A string field for the html that will be passed back.

Output

  1. storedRawTemplate: The HTML stored on the SparkPost server.

LibraryEndPoints

This function simply spits out some documentation on the library functions that are available.

So there you are! A small PHP library to help you validate that the data you’re sending to a template is the data the template needs. I hope that this library will grow over time, and if I add anything to it, I’ll blog any of those updates. Please feel free to add new capabilities; it would be great to see new features shared across the SparkPost community.

-Jeff Goldstein

 

 

Related Content

Leveraging Substitution Data and Templates to Personalize Emails

Jeff Goldstein explains how to leverage substitution data and templates to separate the work of obtaining data for personalized emails and the creative for those emails.

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

How And Why We Simplified The SparkPost PHP Client Library

Introducing our PHP 2.0 Library. Check out the changes we’ve made to keep up with the complex areas of our API additions for our PHP client library users.

read more

Get started and start sending

Try SparkPost and see how easy it is to deliver your app’s email on time and to the inbox.

Try Free

Send this to a friend