External data feeds

Add external data feeds to your project to fetch personalization data at send time, so you can personalize messages at will.

External data feeds let Airship fetch personalization data from an external API when you send a message. Using feeds can help you tell your audience about things they might be interested in, without having to send custom events to Airship or assign AttributesMetadata that you can use for audience segmentation. Attributes differ from tags in that when evaluating users with attributes, Airship uses operators, e.g., equals, less than/greater than, contains, before/after, to determine whether or not to target a user. Supported attribute types are TEXT, NUMBER, and DATE. .

For example, if your audience requests weather updates, you can set up an external data feed to fetch weather data when you send your message and personalize messages with relevant weather updates for each member of your audience.

Variables in the Feed URL

You can set both send time variables and standard personalization variables. Use square brackets ([[var]]) for values that you want to set at the message or campaign level, and use standard HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}} to complex evaluations of personalization data. ({{var}}) for audience variables — attributes, custom event properties, etc.

For example, the feed URL below has variables for msg_purpose, first_name, and last_name.

Example personalized feed

The first_name and last_name are populated from audience variables — attributes or custom event properties.

Using the API, you set the msg_purpose value in the #feed block for each channel’s message. Using the dashboard, you set a value in the Delivery step, and that value applies to all channels selected for that message. So, if your messaging campaign includes App, Web, and SMS channels, you can set msg_purpose in the #feed block with different values for App, Web, and SMS channels, or you can set a value in the Delivery step that applies to all of the channels in the campaign.

Set a variable at the message level
{{#feed "myfeed" msg_purpose="weather" as |weather|}}
    Hi, {{first_name}},
    It's going to be {{weather.temp}} in {{weather.city}} today!

Set a variable at the campaign level (in the Delivery step)

Feed Object Locations

You access properties from your feed using JSON dot notation in the #feed block. When you set up your feed, you can define objects in your feed’s response so that you don’t have to remember the exact name and location of every property in the feed.

Airship lists the object locations you define along with your feed, making it easy to reuse properties from your feed in messages and templates.

To add an object location, provide the path to the variable you want to reference in JSON dot notation, and a friendly name for the property.

Enumerate object locations when configuring a feedUse known object locations in the feed

Personalizing Messages with Feeds and Other Sources

You can reference variables (or merge fieldsA variable in your message or template that you want to populate with a personalized value for each member of the audience. Merge fields use Handlebars syntax — {{merge_field}}. ) that aren’t a part of the feed — attributes, custom event properties, etc. If this is something you may do, set the feed namespace using as |alias| to differentiate between properties from the feed and other personalization variables. This ensures that Airship uses the proper variables in your messages.

In the example below, we can differentiate between attributes (first_name and user_id) and feed properties based on the parent namespace set within the feed and each blocks.

{{#feed "featured_products" region="us" as |result|}}
Hi {{first_name}}, take a look at
  {{#each (limit result.products 2) as |product|}}
    {{product.name}}: {{product.price}}
    https://example.com/us/{{user_id}}/featured/{{urlEncode product.slug}}/
    Products that might interest you at https://example.com/us/products/featured
Couldn't fetch featured products!

Feed Throttling and Caching

Personalization using external data feeds can mean a lot of API calls in a short period of time. With throttling, you can configure a frequency rate for your requests. You can also cache responses from your feeds and use them for multiple recipients. You may want to cache a response if you don’t expect your feed to return a different response when using the same feed URL and parameters.

You enable the Cache response and Throttle requests options when you add a feed to your project. You can enable one option for a feed, not both.

Feed Success, Retry, and Error Conditions

Airship considers any 2xx response from your feed to be a success and will continue a message using your feed response.

Airship considers any 3xx, 4xx, and 5xx codes (except 502/503) to be error conditions. You set the error behavior for your feed when you set up your message, determining whether to send a message without your feed or to abort the message — either in the Delivery step in the dashboard or with the on_error object in the API.

HTTP StatusResultBehavior
2xxSuccessAirship uses the feed response, even if empty.
3xxErrorError behavior determined by user.
4xxErrorError behavior determined by user.
5xxErrorError behavior determined by user.
timeout (60s)RetryUp to 4 retries, 60s between attempts.
502/503RetryUp to 4 retries, 60s between attempts.

Set Feed Error Behavior

When using an external data feed in a message, you determine what happens if the feed fails — whether to abort the message or send it despite the error. If your message still makes sense without a feed, you may want to send the message even if your data feed fails.

When you set up a message that uses a feed (or use a template that includes a feed) in the Airship dashboard, you set Failure behavior in the Delivery step.

When using the API, you can set the on_error behavior to continue to send messages despite an error. Otherwise, a feed failure will prevent Airship from sending your message.

    "feed_references": {
        "feeds": [
                "name": "featured_products",
                "params": {
                    "region": "us"
                "on_error": "continue"

Feed Retry Conditions

Airship will make up to five attempts to get a response from your feed, retrying after 60 seconds if we receive 502/503 responses, or if the feed does not respond after 30 seconds.

If after five attempts Airship does not receive a 2xx response, we’ll consider the feed failed and use the error behavior that you set for your message.

Set Up a New Feed

When you set up a feed, you provide Airship with the endpoint and any HTTP request headers required to successfully communicate with the external feed (e.g., authorization headers). You can even use variables in the feed URL, so that you can provide variables at send time and ensure that your data feed uses data relevant to your audience.

You will identify and use your feed in handlebars by the Feed ID. Feed IDs are unique and cannot be changed. When you create a feed, make sure you set a Feed ID that is meaningful to use and relatively easy to type.

  1. Go to Settings » Project Configuration and click Manage for External Data Feeds.

  2. Click Add data feed.

  3. Enter feed information.

  4. (Optional) Enable Cache response if you want Airship to cache the response from your feed and use it for multiple recipients.

  5. (Optional) Click Add header to add request headers, e.g., Authorization. For each header, enter a Key and Value. Header values support handlebars as well, so you can populate header values from attributes and other personalization sources.

  6. Click Next.

  7. (Optional) Enable Throttle requests to configure a frequency rate for your requests. Enter the number of API requests per second. The minimum rate is 100 requests per second. This option does not appear if you enabled Cache response.

  8. Confirm that you have rights to make requests from the Request URL, then click Next.

  9. (Optional) Click Add object location to map objects in the feed’s response to a different key that is easier to remember or type. Enter a name and object location. For example, if you have a user object, you might want to access the first name of your user. Enter firstName as the Name for the data and user.firstName as the Object location. See Object and Array Notation for more detail.

  10. Click Save.

Using a Data Feed in a Template or Message

In templates, email, and Message Center messages you can copy HandlebarsHandlebars is Airship’s templating language for personalization. Handlebars expressions use double curly braces wrapped around a content template, ranging from a simple variable, e.g., {{first_name}} to complex evaluations of personalization data. for your feeds from the sidebar, then paste them in your message content:

  1. Click Data Feeds to see your list of feeds.
  2. Click   to see a feed’s details.
    • The first (top) entry is the feed itself.
    • Subsequent entries are object locations that you added when setting up your feed, making it easy to reuse properties in your feed.
  3. Hover over an entry and click   to copy.
  4. Select a text field in your message and paste the copied data.

In all other messages you can reference a feed by adding a block in the format {{#feed "feed_id"}}Content referencing the feed{{/feed}}.

In both cases, if your feed URL has variables in the format [[var]], you can set those variables in individual feed reference as {{#feed "feed_id" msg_var="value"}} or in the Delivery step in the dashboard. If you do not set a variable, Airship uses the default value that you assigned when setting up your feed.

Whenever you use a feed in a message, you must set the error behavior for the feed in the Delivery step.

External Data Feed Reporting and Errors

When you use an external feed in a message, its message report shows the feed that you used. It appears in the Content table in the Message Detail section of the report.