This post only applies to Legacy Version 3 of the API If you have been sending personalized messages to your contacts, then you already understand how useful this marketing technique can be. If you would like to start exploring how to use personal information you have about your contacts, take a look at this post by Frank Chapman on Getting Personal With Your Contacts.  But what about those of you that are sending messages with data that isn't available until you send the message? API message tags to the rescue! You can think of API message tags as place holders that you can fill in with data when you send a message through the API. Adam Covati touched on API message tags in Owning Automated Messages. API message tags are clearly useful in the case of a receipt or some other transactional type of message like the following example. You will notice that the message tags can exist within the context of an HTML tag, as is the case with the address fields in the table. The %%#items%% tag could be passed in as a table, or could be a simple list of items. Since API message tags are just empty place holders, they can be used for anything that you want to contain up to date/personalized information, or data you don't have at the time the message is designed.

Setup

So let's make sure you know how to pass this data in from the development side. If you take a look at the documentation for the writeDeliveries function, you will notice the optional fields parameter. This is an array of messageField objects which contain the name of the field, the type, and the actual content. The type is the type of message for which the data is destined, not the type of the data. In some cases, the difference between the data you send into an HTML message and the data you send into the text version of the message will be different. A transactional purchase receipt, for instance, would likely contain a list of items purchased. The HTML version of the message might get an HTML table structure, while the text version of the message would get a simple comma separated list of items.

Passing In HTML

Wait a minute, HTML? That's right! You can pass in more than just a simple name of an item, or a purchase price. You can even make styling or formatting decisions at send time. You would probably want to leave most of the styling to your email designers, but clearly there is the opportunity to do a lot of interesting things with API message tags. Hopefully you can now see how useful API message tags are. If you have been using the API and wondered what these optional tags were, run to your nearest code editor or IDE and send some messages with personalized information courtesy of API message tags.

Alex Durzy
Support Engineer at Bronto