Call an External Data Feed

Follow the instructions below only if you do not use a Content Feed or import your site's external feed. Those options are recommended over directly accessing an external feed. (See Data Feeds Overview.) Use the following methods for a data feed URL directly entered into the data feed box of the campaign editor or directly specified via API.

JSON Data Feeds

The most flexible custom data feed format is JSON. If you provide your data in JSON format, you must use the MIME Content-type header application/json or text/javascriptIn JSON format, you can pass any data you want in the form of a single JSON object. However, be sure to include a "url" field, as this is required for the feed to load. The top-level keys of the object represent replacement variables in the body of your message. For example, if you had the feed:
{"main_title":"Today's Email Blast", "headlines":[
      {"title":"Headline 0","url":"http://example.com/headline-0"},
      {"title":"Headline 1","url":"http://example.com/headline-1"}
]}
You could reference the variables in your HTML code with {main_title} or {headlines[0].title} If you're not familiar with programming, please note that arrays, such as the above, always start at "0" not "1".

JSON Key Rules: Separate words with an underscore ( _ ) instead of hyphen ( - ). You cannot reference keys values with hyphens in Zephyr.

  • Bad: {stream[0].vars.sailthru-doctor}
  • Good: {stream[0].vars.sailthru_doctor}
If you must use a hyphen in a JSON key, wrap the key with square brackets ( [] ) and single quotes ( ' ) on the template level. You can how reference these values in Zephyr.
  • Bad: {content.real-estate[0].title}
  • Good: {content['real-estate'][0].title}

 

XML Feeds

XML feeds are converted to JSON in a fairly straightforward way:
  • Individual elements become individual keys
  • Attributes are represented as a key named @attribute
  • When attributes are mixed with content, the content is represented as #text
For example, if your XML looks like:
<myxml>  <main_title>My Main Title</main_title> <headline title="Headline 1">http://example.com/headline-1</headline> <headline title="Headline 2">http://example.com/headline-2</headline></myxml>
Then: My Main Title {myxml.headlines[0]['@title']} Headline 1
{myxml.headlines[1]['#text']}
If are creating a new feed specifically for the platform and you have a choice of whether to use XML or JSON, use JSON as it is more straightforward. But XML is very convenient when you are using existing feeds such as RSS.  

RSS Feeds

Since RSS feeds are a common XML feed that most sites already have, it's easy to use your existing RSS feed as your data feed with little development effort. Typically, you will loop through the rss.channel.item array and print each title and link This can be accomplished as follows:
 {foreach rss.channel.item as item} 
    <a href="{item.link}">{item.title}</a> 
 {/foreach}

We recommend that you convert your RSS feeds to content feeds instead of calling it directly from your template (see Data Feeds Overview).

Step by Step Tutorial: RSS/XML

  1. Go to the "Campaigns" section and hit the "Create New" button.
  2. Under the advanced tab, select custom "Custom Feed URL" and enter the following URL: https://www.sailthru.com/service/examplerss.xml
  3. Enter the following Zephyr code:
    {foreach rss.channel.item as item} 
       {item.title}
       {item.description}
    {/foreach}
  4. click on the HTML Preview tab, you should see:
    First Item   This is the first Item in our example feed   
    Second Item  This is the second Item in our example feed   
    Third Item   This is the third Item in our example feed

In order to make custom parameters in your RSS or XML feed accessible when importing it as a content feed, perform the following steps:

  1. Change the namespace declaration to: http://www.sailthru.com/rss-extension
  2. Nest your custom parameters within the <sailthru:vars> tag. This should be a sub-element of <item> or <channel> and can contain any data you need, including nested variables. For example:
    <rss version="2.0" xmlns:sailthru="http://www.sailthru.com/rss-extension">  <channel>  
    <title>Example RSS Feed</title>  <link>http://www.example.com/rss/feed.xml</link>  <language>en-us</language>  
    <pubDate>Fri, 08 Nov 2013 15:14:19 -0400</pubDate>  <lastBuildDate>Fri, 08 Nov 2013 15:14:19 -0400</lastBuildDate>  
    <description>Example RSS feed showing use of sailthru:vars</description>  <image>    
    <url>http://www.example.com/example/image.png</url>    <title>Example</title>    
    <link>http://www.example.com</link>  </image> 
     <sailthru:vars>    
    <sailthru:examplechannelvar1>example channel value 1</sailthru:examplechannelvar1>   
     <sailthru:examplechannelvar2>    
    <sailthru:examplechannelnestedvar1>example nested value 1</sailthru:examplechannelnestedvar1>    
    </sailthru:examplechannelvar2>    </sailthru:vars>  <item>   
     <guid>http://www.example.com/example/item.html</guid>    <title>Example Article</title>    
    <link>http://www.example.com/example/item.html</link>    <pubDate>Fri, 08 Nov 2013 16:54:14 -0400</pubDate>   
     <sailthru:vars>      <sailthru:examplevar1>example value 1</sailthru:examplevar1>      <sailthru:examplevar2>     
     <sailthru:examplenestedvar2>examplenestedvalue2</sailthru:examplenestedvar2>      </sailthru:examplevar2>   
     </sailthru:vars>    <description>      Example description
        </description>  </item></channel></rss>

Raw HTML

You can also just get a piece of HTML and put it into your email. This approach is discouraged, as it is better to separate your content from presentation, but it is supported. Simply serve your data feed content as text/html and the entire contents of the feed will go into a replacement variable which you can reference as {html}