Table of Contents:
Table of Contents
| Info |
|---|
|
Subsection Pages
Child pages (Children Display)
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 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
| Code Block |
|---|
{{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.
...
| Code Block |
|---|
{{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 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.
...
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
| Info |
|---|
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:
...
- 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):
| Code Block | ||
|---|---|---|
| ||
<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
| Info | ||
|---|---|---|
| ||
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.
| Code Block |
|---|
{
"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:
| Code Block |
|---|
{
"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.
...
| Code Block |
|---|
{
"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:
...
| Code Block | ||
|---|---|---|
| ||
<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
| Code Block |
|---|
// 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:
...
| Code Block |
|---|
{
"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
| Code Block |
|---|
{{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
| Code Block |
|---|
{
"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.
...
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 feed 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 feed and that will work fine.
...
| Code Block |
|---|
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 Feed in Email:
{{ocx_feed_html{url=http://some-domain1.com/homepage}}}
{{ocx_feed_html{url=http://some-domain2.com/lastpage}}}
Two Dyanmic Feed 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 |
...