Blueshift supports the capability to include dynamic content from external servers that is fetched “just in time” before sending a message. This External Fetch capability is currently available for email, SMS, Push, In-app, and Custom Apps templates. Before you can use External Fetch in your messaging templates, you must first set up an External Fetch template. 


You can use the external fetch response as dynamic message content or for conditionally showing content based on Liquid expressions. Some use-cases that leverage this capability include:

  • Run real-time inventory/product availability checks before sending a message.
  • Automatically sign-in a user with authenticated links that include a personalized user token on each email link.
  • Include dynamic content such as ads, blogs or conditionally display content based on availability.


Campaign execution performance will depend on latency of the external fetch server and will be lower than campaigns that do not fetch content externally. Certain requirements must be ensured in order to ensure smooth execution.

  • The external fetch server should respond with valid JSON within 500ms including any network delays from our server (i.e. timeout is 500ms). In case of any connection or network failures, Blueshift will attempt to reconnect up to 5 times with exponential-backoff before the message fails and the user is skipped.
  • Blueshift computes campaign messages in parallel to maximize throughput, the external fetch server will need to support a high-degree of concurrency with low latency for successful message delivery.
  • You must follow these conventions, which are standardized for handling HTTP status codes:
    • Send us a 200-299 status code if it is successful.
    • If we get a connection error related status code (408, 502, 503, 504), we will retry up to 3 times.
    • Everything else is considered an error. Our recommendation is to send either a 412 or 422 if you have determined not to message a user.

Authentication for External Fetch

You can use any authentication scheme for external fetch.  You must use https if you are going to use authentication.

Here is an example of how to use HTTP basic authentication to secure your external fetch endpoint.

  • Basic authentication requires that you set an “Authorization” request header field.
  • The value of this field should be “Basic“ followed by the base 64 encoded value of the username and password joined by a colon.

There are many online tools out there that can generate the base 64 encoded value, but we recommend that you request one of your internal developers to do it for you.

For example, for the username = “user” and password = “password”, a base 64 encoding of “user:password” gives you “dXNlcjpwYXNzd29yZA==\n”. The value you send for the “Authentication” request header would be “Basic dXNlcjpwYXNzd29yZA==\n”.

Set up External Fetch

Setting up external fetch for most templates consists for the following two steps:

  1. Create an external fetch template.
  2. Include the external fetch template in the messaging template.

Create external fetch template

You can view all your external fetch templates by going to Templates > External Fetches.

To add an external fetch template, complete the following steps:

  2. In the Alias Name field, add a name for the template.
  3. Set the HTTP Method as Get or POST.
  4. Add the external URL. The external fetch URL may include dynamic liquid variables such as user id, email address, product ids and more.
  5. You can include the Auth Header and Auth Token details for secure URLs.
  6. Click Save.

Note: Recommendation data is not available in the external fetch template itself, so if you include liquid in the URL, Auth Header or Auth Token, the “Test API” might not work on this page, but it should work within the creative studio.


Call External Fetch Template

Once you have created an external fetch creative, you can call it from the ‘External Fetches’ section of the creative studio. You can add multiple external fetch templates to your email, push or cloud app template. 

  1. For Cloud app and In-app templates, go to the External Fetches tab of the template studio.
  2. For email and push templates, go to the Data tab of the template studio.
  3. In the External Fetches drop down, select the required templates.
  4. Click Test External Fetch to test the data.


Use external fetch data in your template

During campaign execution, the external url is called and external data is fetched just before the message is sent. Once the content from the external URL is available, the JSON response is parsed and available as Liquid variables under the external_fetch prefix. You can include these variables in HTML templates with Liquid variables.

For example:

  • {{external_fetch.userId}} - for the legacy external fetch functionality
  • {{external_fetch.external_fetch_name.userId}} - for the latest external fetch functionality

Set up External Fetch for legacy email templates

For legacy email templates, you can set up External Fetch from the Data tab of the email template studio. 

To add an external fetch to your legacy email template, complete the following steps:

  1. Open the email template.
  2. Go to Data tab > Configuration Data > External fetch.
  3. Add the external URL. The external fetch URL may include dynamic liquid variables such as user id, email address, product ids and more.
  4. You can include the Auth Header Key and Auth Header Value details for secure URLs.
  5. Click Test External Fetch to test the data.

The external URL endpoint hosted on your server, should respond to a HTTP GET request with valid JSON. The external fetch URL may include dynamic liquid variables such as user id, email address, product ids and more.



Was this article helpful?
1 out of 1 found this helpful



Please sign in to leave a comment.