Guide to Adding a Custom Web Feed in an Email

read
Last updated at:

Overview

In this article, we walk through adding and using a custom web feed within an email. A custom web feed allows you to dynamically populate a feed of data from an external URL within a Klaviyo email. Before sending an email, Klaviyo makes an HTTP request to the URL and fetches the data. The content of the web feed is then available for use in your email.

The power of web feeds is that they allow you to use a single template and pull in content dynamically, where you only need to keep the feed up-to-date and Klaviyo will ensure fresh content from your feed gets populated into every send.

This article will go over adding and using a custom web feed in campaigns and flows.

Feed Requirements

The first step to adding dynamic external content to any email in Klaviyo is creating your web feed source. Your feed content must be hosted at an accessible URL, in either JSON or XML format, and the max. supported size is 3.9 MB. Additionally, your feed cannot utilize a redirecting URL as Klaviyo will not follow any URL redirects for custom web feeds. Flows or campaigns using a web feed with a redirecting URL will experience email sending cancellations consistent with a problematic web feed (see Test or Validate Your Feed below). 

Klaviyo will make an HTTP request to your specified URL and fetch your feed data. Due to how flow emails send continuously, Klaviyo will keep your feed content up-to-date by periodically querying your feed URL to pull in refreshed content:

  • 15-Minute Refresh: Klaviyo will attempt to refresh your feed every 15 minutes. In order to accomplish this, your feed must load within five seconds and return with a successful response.
  • Nightly Refresh: If your feed takes longer than five seconds to return, after three hours of trying, we will start trying to update your feed nightly instead. For ongoing nightly refreshes, your feed must load in under 30 seconds. 

If we cannot load your feed within 30 seconds for three nights in a row, you will not be able to use this feed in your emails. Flow emails relying on this feed will stop sending, and campaign and flow emails will not send until the feed is removed or the outstanding issue with your feed is resolved.

When we query your feed, if we get an error response, we will be unable to access your feed content. We will follow the same pattern as above and retry for up to three days. In the meantime, emails will not send.

If we are having trouble accessing your web feed, you will receive in-app and email notifications letting you know. An easy troubleshooting step is to double check the feed requirements and make sure they fit the parameters outlined above. 

Should you make changes to a feed — for example, reduce the size to speed upload time or fix an issue causing an error response — and would like Klaviyo to attempt a new refresh, navigate to the feed in the Data Feeds tab and click Update Data Feed. We will test and re-validate your feed. If your feed is valid & returns a timely response, we will resume trying to keep your content up-to-date. This is a good troubleshooting step to try if you are having trouble accessing your web feed, even if you have not made changes. 

Adding a Custom Web Feed

To add a web feed, navigate to the Data Feeds tab. If you haven't added a data feed before, you'll see a screen like this:

Click Add Web Feed.

You need to populate the following fields:

  • Feed Name: the identifier you use in your template to access the feed contents. Give your feed a short descriptive name. We recommend naming feeds either in camel case (e.g., "MyDataFeed") or all uppercase with spaces replaced by underscores (e.g., "MY_DATA_FEED").
  • Feed URL: the endpoint Klaviyo uses to fetch the feed contents. If your feed contains private information, we strongly recommend using an HTTPS URL and including a nonce query parameter to secure your feed.
  • Request Method: specifies the HTTP method that will be used to request your feed. We generally recommend GET, but you can also specify POST.
  • Content Type: specifies the format of the feed. The supported types are JSON and XML. We recommend using JSON if possible. For XML feeds, the feed will be converted to JSON.

Once you've filled out all the fields, click Add Data FeedWe will attempt to query the Feed URL you provided and validate your feed is working properly. If we encounter an error, you will see an error message and will be unable to save this new feed until the issue is addressed. 

Want to try this out but don't have your own web feed URL? Use ours. Copy the following URL for the Klaviyo Help Center into the Feed URL box and try it out in your own Klaviyo account.

https://klaviyo.zendesk.com/api/v2/help_center/en-us/articles.json

Klaviyo validates your feed and shows any potential errors. Once validated, you see your feed in Klaviyo and it's ready to be used in emails.

Previewing Your Web Feed

It's useful to preview a web feed before adding it to an email. To do this, click the Preview button in the upper right.

Preview_a_web_feed.png

You can also preview by clicking the Edit dropdown menu from the Data Feeds tab, and selecting Preview.

When previewing your feed, you will either see the feed content or an error message if we cannot load the feed.

If your feed is a JSON array, we'll automatically parse and show each row individually. If it's anything else, most likely a JSON dictionary, we'll show the entire dictionary.

If you are actively developing your feed, you can use the Refresh Feed button to pull the latest version of your feed. The preview page for a feed shows the entire feed. If your feed is large, it may take several seconds to display the contents. Keep in mind if your feed takes over 30 seconds to query, this will impact the performance of any emails relying on this feed.

Once you've added a web feed and previewed its contents, you can use it in an email.

Using a Web Feed in an Email

First, create a new email, either through a flow or by creating a new campaign. Once you've selected a template and are editing the email body, you can add one or more feeds to your campaign or flow email. In the footer of the email editor, click the Data Feeds link. Select the web feed you want to include in your email.

For campaigns, Klaviyo will fetch each feed once per send, and store the returned content. Even if you're sending to thousands of recipients, Klaviyo won't make thousands of requests to your servers.

Test or Validate Your Feed

If you receive an email or in-app notification that we are having trouble accessing your web feed, navigate to your feed and click the Update Data Feed button.

When you click to update your feed, you will see the button change to Validating Feed.

There are two types of error messages that you will see:

  • Invalid Response: If we receive an error response when attempting to query your feed content, we will tell you the status code of the error. You will need to address the issue causing this error response before the feed can be successfully used within any email.
  • Performance Issue: If we do not get a response from your feed within 30 seconds, this will lead to sending delays. While you may have been able to save your feed historically, to mitigate the risk of sending delays, you will need to address the performance issue with your feed before re-validating and successfully saving it.

In both cases, if you use a problematic feed within a send, this will lead to sending delays or your email may be cancelled altogether. For flows, it is also likely emails are not sending. We recommend removing a problematic feed from all emails while you address any outstanding issues to prevent sending disruption.

Populating Feed Content in Your Template

The process for adding feed content to your emails varies if you're using a JSON Array or a JSON dictionary. We cover both methods in the sections below.

Using a JSON Array

In our example web feed, we have an array of locations where each entry includes a name, description, and image. After a feed is added to an email, it's available through the feeds variable:

{{ feeds }}

For example, for the JSON feed above, we can now reference or output the contents of the tourists feed by including this syntax in our template:

{{ feeds.KlaviyoBlog }}

Let's run through an example where we iterate over all entries in the array, displaying certain variables. We'll use the Klaviyo Blog feed as an example here, and iterate over Images.

Step One: Insert a New Text Block

Simply drag a new text block into your email and place it where you want the web feed to populate.

Step Two: Turn on the Repeat Block Feature

To do this, click on the small hamburger menu in the upper right-hand corner of the text block.

For the Repeat For field, insert: feeds.YOUR-FEED-NAME

In our example, because we are iterating over the "items" value as well, we will repeat for: feeds.KlaviyoBlog.items.

For the Item Alias field, insert: item

2017-11-06_16-20-27.png

If you only want this block to iterate over a certain number of entries, use the "slice" filter. To use this filter, adjust the Repeat For value by adding the filter to the end: 

feeds.KlaviyoBlog.items|slice:':3'

In this example, |slice:':3' will cause only the first three entries to display. 

Step Three: Insert Variables

Once you have configured the Repeat Block feature, you can insert whichever variables you'd like using the "item" alias, such as:

{{ item.name }}
{{ item.images }}

Step Four: Preview

When you preview your template, you will notice that the Repeat Block feature will allow this simple text block to automatically iterate over all entries in your feed. Only the variables you specify in the text block will show for each entry.

If you are inserting an image, please note that you will need to edit the Source area of the text block and contain the image in an <img src> tag. 

2017-11-06_16-37-07.png

Using a JSON Dictionary

Example: Iterate over all blog entries from a custom RSS feed

When you add a new RSS feed and click Preview, you will most likely see the following structure:

rss: { 
         ..... 
         channel: { 
                 ..... 
                     item: { 
                             .....}}}

Step One: Create a Dynamic Table

You can alternatively use the Repeat Block feature outlined in Step Two above.

To create a dynamic table, drag over a regular Table Block and adjust to one column (removing the header text). Click over to Rows, and toggle the block from Static to Dynamic.

Step Two: Establish Data Source for Dynamic Table

Click on the Data Source tab after toggling your table to Dynamic. Insert the following as the source Row Collection field:

feeds.NAME OF FEED.rss.channel.item

Insert the name of your feed where you see NAME OF FEED. Set the Row Alias to "item".

Step Three: Inserting Variables into Table

Next, you need to populate your table with the variables of your choice. You can find these variables when previewing your web feed.

Use of Django Filters

We support the use of all Django filters for the variables you insert. Below are a few commonly used filters, and you can learn more in our guide on Using Filters to Customize Template Tags and the Glossary of Variable Filters.

Show only X number of recent posts

If you only want a dynamic table block to iterate over a certain number of entries, use the Slice Filter

To use this filter, adjust the Data Source value by adding the filter to the end. For example:

feeds.NAME OF FEED.rss.channel.item|slice:':3'

In this example, |slice:':3 will cause only the first three entries to display.

Limit post summary to X number of words

If you want to include a brief summary of each post under the post title (and your feed provides this summary text), you can use the Truncate Filter.

634934

To limit the summary of an article to 250 characters, for example, you may do:

{{ item.summary|truncatechars:250 }}

Additional Resources

 

x
Was this article helpful?
78 out of 182 found this helpful