Content source feeds overview

Content source feeds are data files made up of a list of items and attributes of those items. The feeds can be csv, txt, xml or json API formats. Litmus Personalize can retrieve your feeds to use as a content source. Connect them to your content automation templates for active customization.

Types of feeds

• Product feeds (Google Shopping Feed, etc.)
• RSS feeds (news updates, etc.)
• Latest blog content 
• Currency exchange rates 
• User generated content 
• Instagram API - NOTE: Due to Meta's API integration change, Instagram feeds will no longer update beginning December 4, 2024.
• Twitter API 
• 3rd party API (review provider content, etc.

CSV feeds

CSV files can be comma separated, tab/bar separated and must available to retrieve via HTTP(S). Within the product feed, 1 item should equal 1 row (e.g. all data and attributes for one product should be within one row). All data field names should be unique (i.e. there should not be two columns named 'price'. 

All product feeds are unique but they should all share similar properties and structure. A standard Google Shopping Feed contains these data fields:

• ID 
• mpn / gtin 
• title 
• description
• link 
• image link (+ any additional product images) 
• availability 
• stock level 
• days in feed / date added to feed (required for new in) 
• price 
• sale price 
• color 
• gender 
• size 
• master product category (main category e.g. Clothing, Accessories, Shoes, Beauty, Homeware) 
• product type category (e.g. dress, skirt, coat, shirt) 
• custom labels (can be used to flag products for promotions / events etc.)

Product categories and classifications

In order to automate products accurately, they must be accurately, consistently and clearly categorized. Here is an example:

Each product has a: 

• gender 
• master product category (main category e.g. Clothing, Accessories, Shoes, Beauty, Homeware) 
• product type category (e.g. dress, skirt, coat, shirt) 
• fit (where applicable) 
• size 
• custom label

XML feeds

Extensible Markup Language (XML) is used to describe data. The XML standard is a flexible way to create information formats and electronically share structured data. An XML file containing details on the advertiser's products is a product feed. However, XML files are not limited to products. Blog content, currency conversions and news articles are commonly featured in XML feeds. Each item (product/article) is a new record in the file and includes the product name, description, URL, image links, categories, and prices. The information in a data feed may vary from brand to brand as there is no standard way of creating them.

All product feeds are unique but they should all share similar properties and structure. An XML product feed will contain these fields:

• ID
• mpn / gtin
• title
• description
• link
• image link (+ any additional product images)
• availability
• stock level
• days in feed / date added to feed (required for new in)
• price
• sale price
• color
• gender
• size
• master product category (main category e.g. Clothing, Accessories, Shoes, Beauty, Homeware)
• product type category (e.g. dress, skirt, coat, shirt)
• custom labels (can be used to flag products for promotions / events etc.)

New in items

To automate new in products, we need to be able to identify that a product is 'new', or that it has been recently added to the feed. The best way to manage new in is by a 'date added' field in the feed. Simply, this is the date that the product was inserted into the product catalogue for the first time. Alternatively, if a date is not possible, some brands use a 'newness' value which indicates how many days a product has been in the feed where 0 = new.

Where there is a date column in the feed, Litmus Personalize can order the product feed by date so that products pull through in the order from newest to oldest.

Here's an example of a date added field in a product feed:

If a date / days in feed column is not an option, it is advised to use a custom label and a 'new' flag. This flag can then be used to filter and find products flagged as new. This requires more management and will need regular updates.

Product categories and classifications

In order to automate products accurately, they must be accurately, consistently and clearly categorized.

Each product should have the required information and category, for example:

• gender 
• master product category (main category e.g. Clothing, Accessories, Shoes, Beauty, Homeware) 
• product type category (e.g. dress, skirt, coat, shirt) 
• fit (where applicable) 
• size 
• custom label

XML blog feed

An XML blog feed should contain these fields:

• blog title 
• link 
• description 
• published date 
• author 
• content category 
• blog image

API feeds

Litmus Personalize live-images make an API call to fetch the latest content at the time the email is opened. Business rules are setup, in the interface, to define what content to fetch based on user information, time of open, and other personalization factors required.

Litmus Personalize can call an API to retrieve the required data. We have customers using a number of APIs from 3rd party tech partners, as well and APIs built in house.

We offer a lot of flexibility working with APIs. You can either setup one API to power latest deals for example, or you can create a '1-2-1' API that allows for variable parameters for personalization. You can connect an API directly into Litmus Personalize to retrieve data.

The API should be structured with 1 array with 1 element. All data and attributes for one product should be within one element. All data field names should be unique. The API response should be as quick as possible and must be under 400ms.

When creating the content source we are very flexible. We allow as many different types of content sources as possible. We don't impose a specific protocol. We work with both http and https.

Here is an example API format:

{
	"Products": [{
			"Id": "123456789",
			"Name": "Product 1",
			"ProductDisplayName": "Product 1",
			"NameSpecifications": "Product 1 - 1000 pieces",
			"CategoryName": "Entertainment",
			"Manufacturer": "Puzzle Maker",
			"Price": 10.00,
			"OriginalPrice": 15.00,
			"Saving": 5.00,
			"CampaignLabel": "BESTSELLER",
			"ProductUrl": "http://www.yourdomain.co.uk/product/123456789",
			"ProductImageUrl": "https://yourdomain.co.uk/image/123456789.jpg"
		},
		{
			"Id": "987654321",
			"Name": "Product 2",
			"ProductDisplayName": "Product 2",
			"NameSpecifications": "Product 2 - colouring book",
			"CategoryName": "Entertainment",
			"Manufacturer": "Colour Maker",
			"Price": 1.00,
			"OriginalPrice": 6.00,
			"Saving": 1.00,
			"CampaignLabel": "NEW",
			"ProductUrl": "http://www.yourdomain.co.uk/product/987654321",
			"ProductImageUrl": "https://yourdomain.co.uk/image/987654321.jpg"
		}
	]
}

APIs can be added directly into the Litmus Personalize UI with no customization required.

Testing APIs

You can add and test APIs in the Litmus Personalize UI, however, if the API is slow to respond it may time out. In order to build and serve an image into an email quickly the API must respond quickly. We will wait for 1 second after calling the API. If we do not retrieve the data in that time, we will time out. We recommend using a tool called Postman to test API speed. This is a handy app that provides API response time and makes it easy to test and see API data.

If the API is slow or a default image is being returned you can test the following:

• Add API in Postman with default parameters 
• Test API in Postman 
  • Carry out multiple tests to determine average speed 
  • Test API with personalized variables to see if 1-2-1 calls are slower 
  • Establish if first call is slow then a cache kicks in

If you are experiencing product image slowness or a blank image in your tag, test image load time in your browser using its developer tools.

Protocol support

Litmus Personalize does not require a specific protocol. You can use both http and https depending on what you write in the endpoint, however, https is preferred.

If you are seeing an error, check that your endpoint is correct, either http or https. If you use http in the endpoint and your server only accepts https then we can't fetch any data and will return an error. You will need to edit the endpoint in Litmus Personalize.

API call authorizations

When creating the content source, it is possible to add a header or token to grant Litmus Personalize access to retrieve the content.

API maximum size limits

There is no maximum size. API suitability is determined by response speed. If an API takes a minute to respond, we will not be able to retrieve the content fast enough to build and serve the image live into the email. In this case, we would have to wait 1 minute to get the content and then we would build and serve the image in under 400ms.

In reality, a subscriber would not wait this long to see an image in the email. Therefore the API response should be as quick as possible. Our ideal scenario is a response time that is under 400ms. Litmus Personalize will time out after 1 second and serve the cached image built from the last successful call into the email.

API structure array

The API should be structured with 1 array with 1 element. All data and attributes for one product should be within one element. All data field names should be unique.

Common use cases

Really, the sky is the limit with what's possible using an API. Here are some use cases from our customers: 

• Product Recommendations 
• Latest Deals (retail & travel) 
• Personalized holiday recommendations 
• Live car hire pricing & availability 
• Activities in destination 
• Live currency exchange rate 
• News updates 
• TV schedules 
• Live medal tables for events 
• Live scores 
• Live odds for sportbooks 
• Live loyalty points 
• Shipping updates 
• Latest social content
• User generated content (3rd party) 
• Product / company reviews (3rd party)