Our v3 API is now available! Learn more by visiting the v3 developer portal. Creating new v2 API keys is no longer supported.

Creating Dynamic Content

Dynamic content - What is it? Why do I care?

Campaigns that include content personalized to each subscriber are shown to have a higher engagement level with their audience. Merging dynamic content into a custom code email campaign, which you can import through our API, is a 3-step process.

 Step One:        Decide what dynamic content you want to appear in the email campaign. 
 Step Two:  Add the dynamic content to all intended campaign recipients.
 Step Three:
 Put the dynamic content variables into the campaign. 

If you're logging into your account and using our normal email editor, as opposed to using custom code, use the "Contact Details" section to the left of blocks while editing them to merge dynamic content into the campaign. The guide linked here explains how to create custom links using our online editor. DO NOT follow the instructions here when using one of our online templates; they work differently.

What we're building

To demonstrate the techniques explained here, we'll create a simple email campaign that announces what dance class a contact attended, and what other class they might be interested in. There are five dynamic elements in this campaign:

  1. The contact's first name
  2. The class the contact attended
  3. The class they might be interested in taking
  4. The date of that new class
  5. A link containing the contact's email address

The HTML of the email campaign includes variables that are replaced by the values stored in each individual contact record at the time the email campaign is sent.  

Step One: Contact properties and variables

Contact variables are the placeholders for the dynamic content that will appear in the campaign. Below are fields that are supported both when importing contacts through a file, and when using our API. We recommend choosing either the work OR home type of email address for all of your contacts for consistency.

Contact Property                 Variable Name in Email Campaign Import File Column Name
Email address
$SUBSCRIBER.EMAIL Email Address - Work
-or-
Email Address - Home
First name $SUBSCRIBER.FIRSTNAME First name
Last name $SUBSCRIBER.LASTNAME Last name
Mailing address line 1 $SUBSCRIBER.ADDRESSLINE1 Address Line 1
Mailing address line 2 $SUBSCRIBER.ADDRESSLINE2 Address Line 2
Mailing address line 3 $SUBSCRIBER.ADDRESSLINE3 Address Line 3
Mailing address city $SUBSCRIBER.CITY City
State name $SUBSCRIBER.STATENAME State
Postal (zip) code $SUBSCRIBER.POSTALCODE Zip/Postal Code
Home phone number $SUBSCRIBER.HOMEPHONENUMBER  Phone number - Home
Job title $SUBSCRIBER.JOBTITLE Job Title
Custom Field n (n=1-15)    $SUBSCRIBER.CUSTOMTEXTn Custom Field n

Step Two: Contact Fields

Our standard contact fields are commonly used in emails, but many of our customers have very customized data they want to pull in that don't fit into the categories above. The Custom Field property allows you to store information about each contact that is unique to your needs or business. You can create custom fields ahead of time, or on the fly while you're adding or updating your contacts from a file. You can use either the bulk import multipart or JSON method to add large numbers of contacts.

Custom Field limits

  • Max character limit - Custom Fields are limited to 50 characters in the API; use multiple custom fields to string together longer content. 
  • Max number of Custom Fields - Each contact is limited to 15 Custom Fields through the API.
  • Custom Field names - The API supports very specific Custom Field names that must be in the format of "Custom Field n", where n = 1 - 15 if imported through bulk methods, or CustomFieldn format if using our individual contact API endpoints. 

You can see the JSON for a complete contact here. The custom field names in the file import column heading, contact record JSON through the API, and what is put into the campaign are ALL moderately different, where n=1-15. Our product UI allows you to have custom names for your custom fields, but to utilize custom fields through our API at any step, you must name your custom fields to be "Custom Field n" in the UI.

What's in the Contact Import File

Email Address - Home  First name  Custom Field 1  Custom Field 2  Custom Field 3 
example@domain.com  Emma Ballet Belly Dance Wednesday, September 12th

Step Three: Putting Custom Content into the Campaign

In this example, the first name, email address, and three custom fields are going to be pulled in to render customized content to the recipient. This is the HTML that's either entered into the email_content field in the API, or pasted into the "Advanced Editor" portion of a custom code email campaign in our UI. In some accounts, you'll see this option to use your own custom code at the top of the email template selection page. In others, you can choose the "Want to use your own code?" option in the lower left side of the email template selector page.

You'll have 2 options to choose from there, HTML or XHTML. The HTML campaign content option will track links automatically so that you can see who clicked on what link. It is also less strict, and can be more easy to use. However, you must choose the XHTML option if you want to put custom content inside link URL's as shown below.

<html>
<body>
<p>Dear $SUBSCRIBER.FIRSTNAME,</p>
<h4>Thank you for being a part of our $SUBSCRIBER.CUSTOMTEXT1 class!</h4>
<p>We thought you'd also like this $SUBSCRIBER.CUSTOMTEXT2 class, offered next $SUBSCRIBER.CUSTOMTEXT3.</p>
<p><a href="http://mydomain.com/classes?email=$SUBSCRIBER.EMAIL">Click here to Register!</a></p>
<p>I hope to see you there!</p>
<p>Sincerely,</p>
<p>Your friends at Wallace Dance Co.</p>
</body>
</html>

See the JSON for a complete campaign object here

Previewing and Sending the Campaign

While previewing a campaign or sending a test version of a campaign, you'll see the dollar-notation fields in the email. Contact-specific information is only sent during a LIVE, scheduled send of an email.

Be sure to test your email in a live send to a list containing just yourself when testing your campaign. After you see contact variables filled in properly, make sure all of your contacts have the data you're pulling into the campaign, and then make a copy of the campaign to send to all of your contacts.

Preview/Test

Email Preview

Live Send

Live Email Send