Personalizing Templates with Data Feeds

To retrieve data from external web services at send time and use it to personalize your messages, use data feeds.

As Iterable sends campaigns, data feeds can make per-recipient requests to external web services. Parameters in these requests make it possible for the web services to return data that's directly relevant to specific users.

This article describes how to set up data feeds and use them in Iterable campaigns.

# In this article

To use data feeds to personalize your Iterable templates, follow these steps:

# Step 1: Set up a web service

Data feeds make HTTP GET requests to JSON, XML, RSS and Atom web services, which should return data that you can use to personalize the messages you send. Before setting up a data feed in Iterable, work with your engineering team to set up a web service for it to query.

For example, here's a response from a JSON web service that returns product recommendations based on a user's purhcase history:

{
  "pastPurchase": "Hot Dog Halloween Outfit for Cats",
  "suggestedProduct": [
    {
      "name": "Deluxe Cat Tree",
      "description": "A jungle for your favorite feline buddy",
      "price": 160,
      "imageUrl": "http://img-cache.cdn.gaiaonline.com/0b4be3af7262e023cce39cffa697d4cd/http://i324.photobucket.com/albums/k331/michellepaints/CC_Cat_Tree.jpg
    },
    {
      "name": "Catnip Mouse Toy",
      "description": "Cats go absolutely crazy for this realistic mouse toy!",
      "price": 4,
      "imageUrl": "https://www.crystalclearpet.com/shop/treats/images/catnip-large-mouse-11077a.jpg"
    },
    {
      "name": "Set of 3 Furry Sticks",
      "description": "Dangle this enticing toy in front of your kitty!",
      "price": 5,
      "imageUrl": "http://i01.i.aliimg.com/wsphoto/v1/1944996867/Freeshipping-font-b-Rabbit-b-font-font-b-Fur-b-font-Strip-Funny-Cat-Stick-Cat.jpg"
    }
  ]
}

Click https://static.iterable.com/sample-data-feeds/sample_data_feed.json to see this response, as generated by a sample JSON web service.

# JSON data feeds should return an object, not an array

The response for a JSON data feed must have a top-level object, not a top-level array.

Valid data feed response:

{
  "items": [
    { 
      "name": "Yo-yo",
      "price": 4.99
    },
    {
      "name": "Toy car",
      "price": 10.99
    }
  ]
}

Invalid data feed response:

[
  { 
    "name": "Yo-yo",
    "price": 4.99
  },
  {
    "name": "Toy car",
    "price": 10.99
  }
]

# HTTP response codes

When a data feed queries the URL for its associated web service, Iterable handles HTTP response codes as follows:

Wikipedia provides more details about HTTP status codes.

# Response times

Iterable expects a data feed's web service to return a complete response within 10 seconds. If this does not happen, Iterable re-queries the same web service 3 minutes later. After 5 unsuccessful attempts, Iterable skips sending the message to the current contact.

# Parameters

When data feeds query web services for data, they can provide query string parameters to request information relevant to particular users. For example, a data feed might query the following web service URL:

https://www.example.com/sample_data_feed.json?email={{#urlEncode}}{{email}}{{/urlEncode}}

This URL includes an email parameter that's set to the value of the email field on the contact's Iterable profile (URL-encoded as necessary by the #urlEncode block helper). Iterable replaces URL merge parameters with profile values or values from a campaign's triggering event.

Web services called by data feeds should respond with data relevant to given parameters.

# Other data feed formats

Iterable data feeds can also query XML, RSS and Atom web services. Websites typically use these data formats to publish frequently updated information (such as blog entries or news headlines) for consumption by other software applications. These formats are based on XML and may look similar to the following:

<rss xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
  <channel>
    <generator>NFE/5.0</generator>
    <title>""cold brew"" - Google News</title>
    <link>
      https://news.google.com/search?hl=en-US&gl=US&ceid=US:en&q=%22cold+brew%22
    </link>
    <language>en-US</language>
    <webMaster>news-webmaster@google.com</webMaster>
    <copyright>2020 Google Inc.</copyright>
    <lastBuildDate>Sun, 03 May 2020 22:35:17 GMT</lastBuildDate>
    <description>Google News</description>
    <item>
      <title>
        This Might Be the Easiest Way to Make Cold Brew Coffee at Home - Food & Wine
      </title>
      <link>
        https://www.foodandwine.com/lifestyle/kitchen/french-press-cold-brew-coffee
      </link>
      <guid isPermaLink="false">52780760175588</guid>
      <pubDate>Fri, 01 May 2020 21:58:50 GMT</pubDate>
      <description>
        <ol><li><a href="https://www.foodandwine.com/lifestyle/kitchen/french-press-cold-brew-coffee" target="_blank">This Might Be the Easiest Way to Make Cold Brew Coffee at Home</a>&nbsp;&nbsp;<font color="#6f6f6f">Food & Wine</font></li><li><a href="https://thegadgetflow.com/blog/best-coffee-accessories/" target="_blank">Cold brew or Cappuccino? Make any coffee you want with these coffee accessories</a>&nbsp;&nbsp;<font color="#6f6f6f">Gadget Flow</font></li></ol>
      </description>
      <source url="https://www.foodandwine.com">Food & Wine</source>
    </item>
  </channel>
</rss>

To reference data in an XML, RSS or Atom-based data feed, use the same syntax described in step 4.

# Step 2: Create a data feed to call the web service

To create a data feed in Iterable, navigate to Content > Data Feeds and click Create New Feed. Provide the requested information:

• Name — The name of the data feed. Used to select it in a campaign.

• Template handlebars alias — (Optional) An alias templates can use to reference data from this data feed. Data feed aliases clarify which data feed a merge parameter references—especially in situations where a single template uses multiple data feeds. Learn more about referencing data feeds by alias.

• URL — The URL to a web service that returns a valid data feed

• Format — The type of data the data feed will query from a web service.

• Authorization token — (Optional) A token Iterable adds as an authorization header in the HTTP request to the data feed. Used to authenticate the request.

  NOTE

  It's possible to use an OAuth bearer token as an authorization header, as described in this document. When this token expires, you'll need to manually update the data feed.

• Custom headers — (Optional) Custom HTTP headers to include in the data feed's web service request. Click Add New Custom HTTP Header to add as many headers as necessary.

• Rate limit — The maximum number of times that Iterable can call this data feed per second, across all active campaigns. Useful to make sure that your servers are not overwhelmed with traffic as you send a large campaign. (Rate limits are a beta feature; talk to your customer success manager to enable them on your account).

  • Choose None if there's no limit to associate with this data feed.
  • Specify a Custom rate if you'd like to limit the traffic to a data feed.

# Editing existing data feeds

To edit an existing data feed, navigate to Content > Data Feeds, find the relevant data feed, and click Edit Feed.

# Editing data feed aliases

Aliases improve template readability, making it possible to reference data feeds by name.

To edit a data feed's alias, navigate to Content > Data Feeds and click Edit Alias (in the drop-down menu) for the relevant data feed. This brings up the Edit Data Feed Alias window:

# Deleting data feeds

To delete a data feed, navigate to Content > Data Feeds, click Delete Feed (in the drop-down menu), and respond to the confirmation prompt.

# Step 3: Configure a template to use the data feed

To allow a template to reference data feeds:

1. Open the template and click Edit in the Details area.

2. Check the box in the Data feeds section.

3. In the dropdown menu, select the data feeds your template will use for data.

4. Configure the following items:

   • Cache data feed response (up to 1 hr)

     This option causes Iterable to cache responses to the data feeds referenced by the template, to reduce load on the servers that host them. For each recipient, Iterable determines the data feed URL to query by substituting parameters from their Iterable profile into the data feed's pre-defined URL. If Iterable has a cached response for that URL from within the past hour, it will use that data. Otherwise, it will query the URL.

   • Merge the data feed and user contexts

     Allows the template to reference data feed data with double curly braces ({{productName}}) instead of double square brackets ([[productName]]). Double curly braces can still be used to reference user profile data, too, but if the same field exists on both the user profile and the data feed, Iterable uses the value from the user profile. With this option enabled, a merge parameter can prefer user profile data but revert to data feed data if needed.

   • Use data feed alias

     Allows the templateto reference data feeds by their aliases. Using aliases can make templates easier to read and maintain, especially when they reference multiple data feeds. To learn how to define data feed aliases, read Editing a data feed's alias.

# Step 4: Reference the data feed in the template's content

To reference a data feed in a template's content, use double square brackets or double curly braces (depending on the template's configuration):

• Double square brackets

  Double square brackets are the default way to access data feed data. For example, the following expression references the price of the first item in the suggestedProduct array of the data feed defined above: [[suggestedProduct.[0].price]].

• Double curly braces

  Double curly braces normally reference user profile data. However, when you enable Merge the data feed and user contexts, double curly braces can also reference data feed data. For example, for the data feed defined above, this merge parameter references the price of the first item in the suggestedProduct array: {{suggestedProduct.[0].price}}.

# Referencing data feeds by alias

To use data feed aliases:

• Assign an alias to the data feed in question (on the Content > Data Feeds screen).
• Enable Use data feed alias for the template.

# Step 5: Use the template in a campaign

To use your template in a campaign, select it on the second step of the campaign creation process. Double-check the data feed options described above, then edit, preview, and send your campaign as normal.

# Allowing Iterable's IP addresses for data feeds

If you want to restrict access to your data feed to only Iterable's servers, you can allow requests from Iterable's IP addresses. This is a good way to make sure that only Iterable can access your data feed.

For a list of Iterable's currently circulating IP addresses, you can programmatically retrieve them from this location: https://api.iterable.com/ip-ranges.json. This list contains the IP addresses used for webhooks and data feeds.

# Refresh interval and changes to Iterable's IP addresses

Iterable's list of IP addresses is programatically refreshed every 1 hour (3600s), but it isn't a dynamic list. The list remains effectively static, but we refresh it every hour to accommodate potential future additions or changes to Iterable's IP addresses. The refresh process takes 5 minutes for the changes to take effect.

Iterable reserves capacity on the list for future growth, so it isn't expected to change frequently. However, in the event of a disaster recovery scenario, the entire list can change within that 5-minute period.

To ensure you don't miss any IP addresses, we always maintain a capacity of 3 unused IP addresses on the list for future growth. This means that when we add new IP addresses, we add them to the list and reserve them for later, and begin using the IPs that were previously reserved. This way, we can ensure that the list is always up-to-date with IPs that are in use, and that you don't miss any changes to Iterable's IP addresses.

# Want to learn more?

For more information about some of the topics in this article, check out these resources. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

Iterable Academy

• Product Bite: Data Feeds

Support docs

• Creating Email Templates
• Creating In-App Templates
• Creating Push Notification Templates
• Creating SMS Templates
• Creating Web Push Templates