External Fetch

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. 

Use-cases

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.

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. 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.
    • Rate Limit: If the API endpoint, you're trying to call using the external fetch, cannot support the request volume to match your campaign throughput, please reach out to support@blueshift.com. Include the details of the rate limits for the API endpoint. We will update the external fetch configuration for you such that the API call volume does not exceed your specified rate limit.
    • Please keep in mind though that setting a lower rate limit for your external fetch template will lower your campaign throughput as well.
  • 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:

  1. Click +EXTERNAL FETCH. 
  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.

externalfetch_create.png

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.

externalfetch_include.png

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

Note: By default, Blueshift will not send a message to the user if:

  • The external fetch encounters an error (meaning the API call failed, indicated by a non-2xx HTTP status code).
  • The external fetch succeeds but returns an empty response (either no response body or an empty JSON hash {}). Note that an empty response needs to be truly empty. The system will consider a response with an empty array {"foo": []} as valid data, even though there are no items associated with the key "foo".
    This behavior is controlled by the Do not message the user if the external fetch encounters an error or does not return any data flag (enabled by default) in the Properties tab of the template studio. If the checkbox is unchecked, the marketer must make sure they write a code that prevents the template from rendering content based on empty data fetched externally. 

    handle-external-fetch-error-flag.png

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.

externalfetch_include_email.png

 

Rate limits

If the API endpoint in external fetch template is unable to handle your current campaign volume, please contact support@blueshift.com with your desired rate limits for the API. We'll adjust your external fetch configuration such that the throughput does not exceed your specified rate limit.  Caution: Lowering the rate limit can reduce the campaign throughput.

 

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

Comments

0 comments

Please sign in to leave a comment.