Iterable

The Iterable App allows marketers to directly sync approved content from Contentful into Iterable data feeds. This eliminates the need for manually creating the URL, reducing the risk of errors and ensuring that content updates are propagated to campaigns automatically.

Overview

The app provides the following features:

• A sidebar app that generates a link which can be copied and pasted into Iterable to use it in a data feed.

Requirements

• You must have Space Admin access to the Contentful space where you are installing the app.

• The Contentful API key to access to the Content Delivery API.

  NOTE: If needed, you can also create a new API key from the API keys menu in settings. You have to provide the Content Delivery API access token.

• A configured Iterable account.
  

Setup and usage

Step 1: Install the Iterable app in the Contentful web app

To install the Iterable app in the Contentful web app:

1. Log in to the Contentful web app.

2. Click Apps, and select Marketplace.

3. Navigate to the Iterable app and select it. The “App details” window is displayed.

4. Click Install. The “Manage app access” window is displayed.
   

   

5. Under Environments, select the environments in which you want to install the app.

6. Click Authorize access. The configuration window is displayed.

7. Under “Configure Access”, enter the value in the following field:

   • Contentful API key — Enter the Contentful API key that Iterable will use to request your content via API at send time.
     

     

8. Optional: Under the “Assign content types” section you can add content types that will be displayed in the sidebar as a widget for entries with that type.
   

   

9. Click Install to selected environments. The Iterable app is now installed in the selected environments and content types.
   

   NOTE: If the following error message is displayed, check to make sure your API key has read access to the CDA: A valid Contentful API key is required.

Step 2: Add Iterable to a content type (Optional)

Once you have the app installed, you can add Iterable to any content type if you haven’t already.

To add Iterable to a content type: 

1. Log in to the Contentful web app.

2. Navigate to the “Content model" tab. 

3. Select an existing content type or add a new one. The content type editor is displayed.

4. Scroll to the “Sidebar” section, and add Iterable from the available items.
   

   

5. Click Save.

Step 3: Use the app

Once you have successfully configured the app in the content type sidebar, open an entry from one of the content types you configured previously.

You’ll see the link in the sidebar. You can copy and use it to create a data feed in Iterable.

Link and endpoint details

This application creates a link that fetches the information that will be used in the Data Feed. It uses the single entry endpoint from the CDA (Contentful Delivery API).

Examples 

This section is meant to help users understand how to use Iterable’s templating language, or Handlebars, with Contentful data.

NOTE: All the Handlebars code shown below is for example purposes. You will need to adapt it to your own context.

By default, information that comes from data feeds must be used with square brackets. When adding the data feed to a Template in Iterable, we recommend selecting the “Merge the data feed and user contexts” option, which allows the use of curly braces instead. Examples are provided using curly braces.

For more information about Handlebars usage, see the Iterable documentation. 

Field types

NOTE: The specific Handlebars syntax to use depends on the Contentful field type you are using.

Text, Number, Date and time and Boolean

These field types can be used directly within a template. For example, for a field name title:

{{fields.title}}

Location

Let’s say you have a content type called venue, which includes a Location field with the ID address. Then, the Handlebars syntax for the location is:

{{fields.address.lat}}

{{fields.address.long}}

This option displays the latitude or longitude specific values.

You can also use the Handlebar in its raw form:

{{fields.address}}

This one displays a structure pair containing all the fields of the location field. Example output:

{lon=-74.006, lat=40.7128}

Rich Text

The rich text field has limited support. When fetched, you get the raw representation of the field, which is a json object that contains the information for each element in the rich text.

This is the information returned by a rich text that contains a heading and a bold sentence.

Assuming the ID of the field is richBody, this is how the Handlebars syntax would look for showing the first element of the content:

{{fields.richBody.content.0.content.0.value}}

Handlebars logic can be used to display all elements of the field with the correct formatting.

Lists

Some Contentful field types can be configured to be used as lists. There are different options to handle that scenario.
Let’s say you have a content type called recipe, which includes a short text field configured as a list with the ID ingredients.

1. You can use the field in its raw form: {{fields.ingredients}}. This option displays all the elements separated by commas and between brackets.

2. You can also use the list to access a specific element through its index: {{fields.ingredients.0}}. This option displays only the element specified by the index.

3. Another option would be to loop through the list using Handlebars syntax:
   

   Handlebars syntax for lists

   {{#each fields.ingredients}} Ingredient: {{this}}</div> {{/each}}

   Copy

   This option allows you to format each element as needed.

Media and references

For reference and media fields, when fetching the entry that contains them, only their ID is returned. For example, if you have a media field with an image ID and you access {{fields.image}}, you will only get the Contentful asset ID. References work the same way.

Use the entries collection endpoint if you need to access the inner information of references or media included in the entry. This endpoint allows to fetch the assets and entries referenced by the fetched entry. Since the endpoint is for collections, a filter can be added to the request so it only returns information for the entry we’re interested in. 

Using that endpoint, the link would like this:

https://cdn.contentful.com/spaces/<space id>/environments/<environment id>/entries?access_token=<access token>&sys.id=<entry id>&include=10

The “include” parameter indicates to include the assets and references in the response. Bear in mind they are included in the “Includes” object in the response, which is a separate object from the entry information. The “Includes” object includes two lists: “Entry” and “Asset”, each containing the referenced entries and assets, respectively. Since this is a separate object from the entry information, Handlebars logic would be needed to match the id of each referenced entry or asset with its information.

The following sections provide examples for media and reference fields using this approach

Media

Let’s say you have a content type that includes a media field. The fields accessible for assets are:

• title

• description

• url

• contentType

• fileName

• size

• width

• height

Example for all of the fields, using the first element of the Asset list:

Reference

Let’s say you have a content type that includes a reference field. The field id we want to access is contact, which is a short text field. We use the “Entry” list to access it.

[[includes.Entry.0.fields.contact]]

Localization

Entry fields can be localized, which means that you can have different values for different languages.

For example, suppose you have an entry of a content type blogPost, with a short text field with id body and two locales available (en-US and es-AR). The Handlebars syntax for these fields will look something like this:

{{fields.body.en-US}}

{{fields.body.es-AR}}

If the entry is not localized, then this is how it looks:

{{fields.body}}