External Fetch

Overview

Blueshift supports the capability to include dynamic content from external servers that is fetched “just in time” before sending an email message. This capability is currently available for email, Cloud App and Push.  Use within other channels coming soon. 

 

Setup & Usage

This feature will be available under the ‘External Fetch’ section of the email, push and cloud apps studio. ‘Depending upon the version you’re on, you will be able to configure external fetch in one of the following ways.

 Legacy Version (for Email Templates only)

Include the external URL in the external fetch section of the Email Template Studio. You may include a token for HTTP authentication for secure URLs. 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.

external_fetch_sample.pngLatest Version

1. Create External Fetch Template

You will first need to create an external fetch template from the Creatives -> External Fetch menu. 

 Ext_Fetch_Menu.png

Include a name, external URL and HTTP method (GET or POST). The external fetch URL may include dynamic liquid variables such as user id, email address, product ids and more. You may include a token for HTTP authentication for secure URLs. 

Please note that the 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” may not work on this page, but it should work within the creative studio.

Edit.png

 

2.  Call External Fetch Template

Once you’ve 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. 

Please note that the latest external fetch functionality allows you to call multiple API endpoints unlike the legacy functionality which only supports a single endpoint.  

Reference.png

 

Template Setup

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

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

 

Authentication Example

Here is an example of how to use HTTP basic authentication (https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) to secure your external fetch endpoint. Other authentication schemes are possible, this serves as an example of what you would do if you chose to use basic authentication. 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. For example, if your username was “user” and the password was “password”, you would do a base 64 encoding of “user:password” to get “dXNlcjpwYXNzd29yZA==\n”. The value you would send for the “Authentication” request header would be “Basic dXNlcjpwYXNzd29yZA==\n”. This screenshot shows a complete example:

Notes: You must use https if you are going to use authentication. There are many online tools out there that can generate the base 64 encoded value for you but it’s safest to ask one of your internal developers to do it for you.

 

Use-cases

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

  • Perform real-time inventory/product availability checks before message send
  • 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

 

Restrictions

Campaign execution performance will depend on latency of the external fetch server and will be lower than campaigns that do not fetch content externally. In order to ensure smooth execution, we require:

  • 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 will need to follow these conventions, which are standardized for handling HTTP status codes:
    1.  Send us a 200-299 status code if it successful
    2. If we get a connection error related status code (408, 502, 503, 504), we will retry up to 3 times
    3. 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.
     

You may reach out to support@blueshift.com if you have any questions on this capability.

 

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