Ongage Feeds: HTML, RSS, XML and JSON
- Ongage OngageConnect
- Noam Rotem
- Stepin\ Shashin Petel
- Pratik Upadhyay
Table of Contents:
For all of the feed commands detailed below, it is recommended to insert the command directly into the HTML code, and not via the Ongage WYSIWYG editor, as the editor may insert CSS code into the middle of the command, thus causing the feed command to fail.
Subsection Pages
The Ongage HTML Feed
Intro
- With the Ongage HTML Feed, you can serve HTML content, residing on a web/content server, and inject it directly into the HTML email message you send from the Ongage platform
- Ongage offers 2 kinds of HTML feed tag technologies: (1) Static HTML Feed and (2) Dynamic HTML Feed
- You can use these feeds to serve up text content into SMS messages as well. For more about that see SMS Campaigns under the Campaigns help section.
The main difference between the static and dynamic HTML feed
Dynamic HTML feeds will call the external content server for each recipient in a given campaign, while the Static HTML feed makes only one call to the content server prior to campaign launch (To be noted: Ongage's Dynamic HTML feed caching feature can reduce the number of calls for each recipient, see details in that section).
- The Static HTML Feed: same content is sent to all recipients in the campaign. The URL cannot contain any dynamic lists fields, as it is the same URL for all recipients.
- Typically used for: daily weather, daily news alerts, daily/weekly what's new/content programming schedule, and any content that would be the same for a given segment, e.g., Boston Events this week to everyone in the Boston segment.
- Dynamic HTML Feed: different content is sent to different recipients in same campaign. To the end of the URL are appended dynamic list field parameters (with values which are unique/specific for each contact).
- As in the example of the Dynamic HTML Feed below, different recipients with different zip codes and different job title values, will get different content based on those values. See more details in that section below including about Ongage's Dynamic HTML feed caching feature.
Static HTML Feed
{{ocx_feed_html{url=... }}}
Place the above html feed tag in the body of your HTML email message:
<html>
<head>
<title></title>
</head>
<body>
{{ocx_feed_html{url=... }}}
</body>
</html>
- Place the Static HTML Feed call in the body of your HTML email message. Above and below the tag you can have other HTML blocks if you like.
- The URL should point to a web server that will be serve up the HTML content and inject it into the email message.
- The above tag will get replaced with the HTML content from that URL (i.e., the content server).
- A call to that URL is made a little before the campaign is sent, and the contents are used to populate the email, that will go out to all the recipients of that campaign. Meaning the same content to all recipients!
- Email Preview works in the case of the Static HTML feed (thought not with the Dynamic Feed detailed below). Click on the preview button will first make a call to the content server, and display it in the preview of the email message.
- The contents served up by the feed can be changed, so that it can be used in a recurring daily/weekly/monthly campaign without editing the email each time.
- For example if you're sending out a daily 'Today's Forecast' email message (or Daily News, Entertainment, Stocks, etc.).
- Note in the case of the Static HTML Feed, you cannot use any dynamic parameters on the URL, for that you'll need the Dynamic HTML Feed in the following section.
Dynamic HTML Feed
See the Intro and Static HTML Feed section above, prior to reading this section.
With the dynamic HTML feed you can add dynamic variables (aka URL parameters, aka query strings), to the end of an HTML feed URL as in the example below:
{{ocx_feed_dynamic_html{url=http://some-domain.com/search/?zipcode={{zipcode}}&jobtitle={{jobtitle}}}}}
Based on the example above a Nurse from Houston, and a Banker from NYC, and a Doctor from Baltimore will all get different content, though all were targeted in the same campaign!
Important precautions when using dynamic HTML feed
- The dynamic feed calls the content server for each recipient in a given campaign, while the static feed makes only one call to the content server prior to campaign launch.
- Meaning if you want to use the dynamic feed, then the server, serving up the content, needs to be robust enough to handle all calls to it, for each recipient, in a fairly short time frame, so that the campaign can go out in a timely fashion.
- Ongage's Dynamic HTML feed caching feature: in order to reduce sending time and load of calls to your content server, Ongage uses a cache mechanism. So for example all recipients that share they same dynamic content e.g. ...&city=Miami&job=Sales – Ongage only makes one call to your server for that content. All subsequent calls with the same values will be retrieved from the Ongage HTML feed campaign cache. The cache remains only for the duration of a single campaign.
- Email preview fully works in the case of the static HTML feed. In the case of the dynamic HTML feed it cannot pull the data for each recipient, so it doesn't work.
- Click Tracking: In the case of dynamic feeds in general, as well as dynamic HTML, there is only one Link ID per campaign, so that there are only aggregated click stats per campaign. This means that click stats and unique click stats will be the same. It also means that only 1 link will appear in the Contact Activity report if there was a click.
Feature: Don't Send Empty Email If Call to Dynamic HTML Feed Returns Failed HTTP For a Specific Contact:
- If the HTTP status code is any number that is not 200, then it won't send the email. Therefore the call to your content server, produces empty content, make sure to return a code other than 200, typically 4xx.
- This feature is currently implemented for the following SMTPs:
Amazon SES
Dyn
Inboxroad
Mailgun
MailJet V3
- MySMTP.eu
SendGrid
SMTP.com
Sparkpost
Sparkpost Enterpirse
The above is the default behavior it can be overwritten with the following parameter:
{{ocx_feed_dynamic_html{url=...,send_empty_content=true}}}
The default is false
How Many Times Does Ongage Try To Retrieve The HTML Feed In Case of an Error
In the case of Static HTML Feed
In this case, Ongage only needs to retrieve the feed once for the entire campaign (one feed for all emails). In this case, Ongage tries 5 times in the following time-span sequence: 10 seconds, 30 seconds, 1 minute, 2 minutes, 5 minutes.
In the case of Dynamic HTML Feed
In this case, Ongage needs to retrieve the feed for each recipient in the campaign and therefore there is no retry for dynamic HTML feeds. Since the delay in theory could happen for thousands, and that could cause unreasonable delay in campaign. Instead Ongage in this case, just skips to next recipient, and does not send an empty email to the recipient with the failed HTTP call.
What is the Feed Timeout
How to Overwrite the Subject of an Email Message from the HTML Feed
This can be used both with the regular Static HTML feed place holder and the Dynamic HTML feed place holder.
You can overwrite the subject of an email message, when you include this designated HTML meta-tag in your HTML feed (meaning the feed will return this meta-tag):
<meta name="ocx_subject" content="This is the new subject" >
The Ongage XML & JSON Feed
Intro
- XML feeds provide you with a way to feed the contents of your email message with dynamic content, from an external source e.g., from your eCommerce/data warehouse server, database or website.
- For example you might update your online website newsletter once a week. The XML feed provides you with a mechanism to take that content and populate your accompanying weekly email newsletter, without having to copy, paste and reformat the content each time into your email newsletter. This is one level of dynamic content
In August 2018, Ongage added support for JSON feed as well. Meaning the URL that you indicate using this place holder, e.g., url=http://yourwebsite.xyz/newsletter/feed/3328/ can return a JSON. Ongage will automatically identify if the feed content is JSON or XML.
The Ongage XML/JSON Feed Place Holder
In the body of your email message indicate the URL of the XML/JSON feed to be used in the body of the message. Below an example of both a static and dynamic XML/JSON feeds:
// Static XML/JSON feed
<body>
{{ocx_feed{url=http://yourwebsite.xyz/newsletter/feed/3328/}}}
</body>
// Dynamic XML/JSON feed allows using dynamic list fields as URL parameters on the feed, so that difference recipients receive different content, based on their personal list field data point values.
<body>
{{ocx_feed_dynamic{url=http://yourwebsite.xyz/travel/newsletter/?d={{destination}}}}}
</body>
- This way you can simply update the content of your feed every day / week / etc. without having to change the contents of your email.
- The contents of the XML/JSON feed you must then format into an HTML email, you'll find info about how to do that in the following sections.
Ongage XML Feed Schema / Structure
The XML to be returned from the URL indicated in the feed command above should be structured in the following manner (with the following XML elements):
<feed> <mailing> <variables> <variable> <key>news_letter_header</key> <value>Best Travel Deals </value> </variable> </variables> <blocks> <block name="block1"> <items> <item> <variables> <variable> <key>offer_title</key> <value>Delightful Bread and Breakfast on the Coast</value> </variable> <variable> <key>offer_url</key> <value>http://yourwebsite.com/delightful_BB_on_coast/</value> </variable> </variables> </item> </items> </block> </blocks> </mailing> </feed>
- Every key in the XML feed can be used as a dynamic variable (aka merge field) in the body of your HTML email. For example in the above {{offer_title}} will display "Delightful Bread and Breakfast on the Coast"
- The block command provides the ability to create a loop of block content e.g.,
- {{ocx_loop{block=block1}}} <!-- Start of loop block, use block "block1" from feed. You can have more than one block -->
- <h1>{{title}}</h1> <!-- Loop body where {{title}} is a key with an accompanying value in the XML feed -->
- <p>{{text}}</p> <!-- and {{text}} is a key with an accompanying value in the XML feed -->
- {{ocx_loop_end}} <!-- End of loop block -->
- {{ocx_loop{block=block1}}} <!-- Start of loop block, use block "block1" from feed.
Variable Scope
In and outside of the loop
Variable Scope
If a variable with the same name exists both as the name of a "list field" and a variable name in the "data feed", then:
When used outside of the loop block: the list field's value will take precedence over the data feed.
When used inside the loop block: the value from the feed will take precedence over the list field.
Overall, in order to prevent confusion, it is best to avoid overlapping variable names.
In the case of nested blocks, the values from the current scope will will take precedence (i.e., be used).
Ongage JSON Feed Structure
Here's a similar sample JSON schema:
Note: you can skip the outer most curly brackets at the very top and very bottom.
{
"feed": {
"mailing": {
"blocks": {
"block": {
"name": "hotels",
"items": {
"item": [
{
"variables": {
"variable": [
{
"key": "name",
"value": "Hilton"
},
{
"key": "location",
"value": "NYC"
}
]
}
},
{
"variables": {
"variable": [
{
"key": "name",
"value": "Hilton"
},
{
"key": "location",
"value": "LA"
}
]
}
}
]
}
}
}
}
}
}
JSON Syntax for Empty Set of Items
In the case that the data feed may not have any available items for a specific recipient, and one would not want to iterate through the ocx_loop, for that use the following data feed syntax:
{
"feed": {
"mailing": {
"blocks": {
"block": {
"name": "hotels",
"items": {}
}
}
}
}
}
How to Set Email Subject (and Email Message Header Fields) with Values from Feed
The Ongage XML feed enables marketers to overwrite the Email Message: Subject, From Email Address, From Name and Reply Email Address with values fed back from the feed.
These XML feed elements are optional (only if you'd like to overwrite the existing one in email message), and are placed after the <mailing> node as in the following XML snippet:
<feed>
<mailing>
<subject>The Subject of the Email</subject>
<from_address> your-from@address.xyz </from_address>
<from_name>Your From Name </from_name>
<reply_address>your-reply@address.xyz</reply_address>
<variables>
...
For full flexibility, there is also the following special instruction, if your XML feed does have a subject, and despite that you'd like to ignore it using the following feed option:
{{ocx_feed{url=……,ignore_subject=true}}}
JSON snippet example for setting subject and email message header fields
Place the "subject" node (and other header fields like "from address"), after the "mailing" node, and before the header "variables" node, as in the following JSON snippet below:
{
"feed":{
"mailing":{
"from_address":"sales@ourbrand.com",
"subject":"The Subject of the Email",
"variables":{
...
XML Feed: Sample Usage
Sample HTML Email using XML field Key/Values inside Loop:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>Your Brand</title>
</head>
<body>
{{ocx_feed{url=http://yourwebsite.xyz/newsletter/feed/3337/}}}
{{ocx_loop{block=block1}}}
<table border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td>
<a href="{{offer_url}}">{{offer_price}}</a>
</td>
</tr>
<tbody>
</table>
{{ocx_loop_end}}
</body>
</html>
Where the XML feed for the above HTML would contain:
<blocks> <block name="block1"> <items> <item> <variables> <variable> <key>offer_url</key> <value>http://yourwebsite.xyz/18317/page-x/</value> </variable> <variable> <key>offer_price</key> <value>498.00</value> </variable> </variables> </item> <item> <variables> <variable> <key>offer_url</key> <value>http://yourwebsite.xyz/18317/page-y/</value> </variable> <variable> <key>offer_price</key> <value>250.00</value> </variable> </variables> </item> </items> </block> </blocks>
Use CDATA Structure to Place Large Blocks of HTML Data in XML Value
If you want to serve up large sections of HTML code, or even an entire HTML email, within the value of an XML variable, you should use the CDATA structure
// Example of what the XML should return in this case:
<variable>
<key>content</key>
<value><![CDATA[... Entire Body of HTML code goes here ...]]></value>
</variable>
// In the body of your email (in the Ongage Editor) you'll then place the following based on the XML above:
{{ocx_feed{url=http://www.someurlfeed.com/newsletter/contents_of_xml.xml}}}
{{content}}
Support for Nested Loops/Blocks
The Ongage Loop/Block construct also supports nested loops. Here's one such example you can use in your email message:
{{ocx_loop{block=hotels}}}
Hotel name: {{name}}
Rooms Available:
{{ocx_loop{block=rooms}}}
Room type: {{type}} Count: {{count}}
{{ocx_loop_end}}
{{ocx_loop_end}}
Sample JSON for Nested Loops/Blocks
Following is a JSON example for the above nested block/loop
{
"feed":{
"mailing":{
"blocks":{
"block":{
"name":"hotels",
"items":{
"item":[
{
"variables":{
"variable":[
{
"key":"name",
"value":"Hilton"
},
{
"key":"location",
"value":"NYC"
}
]
},
"block":{
"name":"rooms",
"items":{
"item":[
{
"variables":{
"variable":[
{
"key":"type",
"value":"standard"
},
{
"key":"count",
"value":"100"
}
]
}
},
{
"variables":{
"variable":[
{
"key":"type",
"value":"deluxe"
},
{
"key":"count",
"value":"15"
}
]
}
}
]
}
}
}
]
}
}
}
}
}
}
Appendix
All Available Feed Parameters
{{ocx_feed_dynamic_html}}
send_empty_content -- default false
entire_body -- default false
For example:
{{ocx_feed_dynamic_html{url=...,send_empty_content=true}}}
{{ocx_feed_dynamic_html{url=...,entire_body=true}}}
{{ocx_feed}}
ignore_subject -- default true
JSON with Multiple Blocks
Sample JSON with multiple blocks
{
"feed":{
"mailing":{
"blocks":[
{
"block":{
"name":"block1",
"items":{
"item":[
{
"variables":{
"variable":[
{
"key":"first_name",
"value":"Jon"
},
{
"key":"last_name",
"value":"Doe"
},
{
"key":"link",
"value":"www.somewhere.com"
}
]
}
},
{
"variables":{
"variable":[
{
"key":"first_name",
"value":"Jane"
},
{
"key":"last_name",
"value":"Doe"
},
{
"key":"link",
"value":"www.somewhere.com"
}
]
}
}
]
}
}
},
{
"block":{
"name":"block2",
"items":{
"item":[
{
"variables":{
"variable":[
{
"key":"city",
"value":"New York"
},
{
"key":"state",
"value":"NY"
},
{
"key":"link",
"value":"www1.nyc.gov"
}
]
}
},
{
"variables":{
"variable":[
{
"key":"city",
"value":"Los Angeles"
},
{
"key":"state",
"value":"CA"
},
{
"key":"link",
"value":"www.lacity.org"
}
]
}
}
]
}
}
}
]
}
}
}
Block Loop with Grouping of Distinct Value
The following features enables grouping nested values under a distinct grouped value as illustrated in the following example.
// The Syntax:
{{StartDate[distinct=true]}}
// Sample Usage:
{{ocx_feed{url=... }}}
{{ocx_loop{block=itinerary}}}
{{StartDate[distinct=true]}} - {{StartTime}} - {{Details}}
{{ocx_loop_end}}
// Sample Output Without Grouping:
Tuesday, January 15, 2019 - 06:30 AM - Airport
Tuesday, January 15, 2019 - 10:20 AM - Hotel
Tuesday, January 15, 2019 - 11:30 AM - Meeting 1
Tuesday, January 15, 2019 - 12:30 PM - Meeting 2
Tuesday, January 15, 2019 - 01:30 PM - Lunch
Tuesday, January 15, 2019 - 03:15 PM - Afternoon Session
Tuesday, January 15, 2019 - 07:00 PM - Dinner
Wednesday, January 16, 2019 - 09:00 AM - Day Off
Wednesday, January 16, 2019 - 07:30 PM - Gala
Thursday, January 17, 2019 - 11:00 AM - Airport
// Sample Output With Grouping:
Tuesday, January 15, 2019 -
06:30 AM - Airport
10:20 AM - Hotel
11:30 AM - Meeting 1
12:30 PM - Meeting 2
01:30 PM - Lunch
03:15 PM - Afternoon Session
07:00 PM - Dinner
Wednesday, January 16, 2019 -
09:00 AM - Day Off
07:30 PM - Gala
Thursday, January 17, 2019 -
11:00 AM - Airport
This feature is useful with Travel organizations who send transactional emails about bookings and itineraries to their clients.
Recommended Response Times for Dynamic HTML Content Servers
- Ongage recommends 0.3 seconds per contact as ideal when using this feature to send bulk campaigns.
- Having said that, response times of up to 1-2 seconds can work as well, depending on the size of your campaigns, and how quickly you need those campaigns to complete. If you're using dynamic feeds for transactional messages only, then response times can even be a little longer.
- Since Ongage's architecture is highly paralleled, you need to take into account that Ongage can open hundreds of parallel connections to your content server in the case of bulk campaigns. If your campaigns are large, and you have multiple campaigns running at the same time, that number of parallel connections can even increase to 1-2 thousand in the most extreme case. That number can be configured on the Ongage side if needed. In the case of bulk campaigns using this feature, we recommend starting with smaller volumes and ramping up.
Using multiple feed in same email
Multiple HTML feeds can be used in same email message. It can be one Static and one Dynamic Feed, it can also be both static or both dynamic feeds, and that will work fine as well.
One Static and One Dynamic HTML feed link example:
{{ocx_feed_html{url=http://some-domain.com/homepage}}}
{{ocx_feed_dynamic_html{url=http://some-domain.com/search/?zipcode={{zipcode}}&jobtitle={{jobtitle}}}}}
Two Static feeds in Email:
{{ocx_feed_html{url=http://some-domain1.com/homepage}}}
{{ocx_feed_html{url=http://some-domain2.com/lastpage}}}
Two Dynamic feeds in Email:
{{ocx_feed_dynamic_html{url=http://some-domain1.com/search/?zipcode={{zipcode}}&jobtitle={{jobtitle}}}}}
{{ocx_feed_dynamic_html{url=http://some-domain2.com/search/?city={{city}}&jobtitle={{jobtitle}}}}}
Structured | Retrieves | Run per | |
ocx_feed | Yes | XML/Json | Campaign |
ocx_feed_html | No | Text/HTML | Campaign |
ocx_feed_dynamic | Yes | XML/Json | Contact |
ocx_feed_dynamic_html | No | Text/HTML | Contact |