Using Fusion (also known as external attributes)

Vero's Fusion feature allows you to pull data feeds from your own API endpoints so you can personalize your messages on a truly one-to-one basis.

It gives you the ability to access data that hasn't been pushed into Vero, and use that data in your message content.

Example use cases:

  • You'd like to send off the top five new products in your store that day.
  • Pull in extra information about your users
  • You'd like to show relevant items based on the current stock.
  • You'd like to send customised content for each demographic (i.e. products based on location or even different languages)

There are two ways to use the Fusion feature:

  1. Using the dedicated "External data source" field when creating a message campaign. Supports adding headers to your API requests.
  2. Using Liquid filters {% fetch_html %} or {% fetch_json %}. Supports multiple APIs in a single message.

You can also use both methods in a single message campaign.

Add an external data source

To add an external data source for your email, you can use the External Data section of a campaign to add the API endpoint that will return JSON data. The JSON response is automatically loaded into a variable named external.

vero.fusion-data-inspector

For example, we can use the following test endpoint to show an example: https://jsonplaceholder.typicode.com/posts/1. This URL returns the following data:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

Using the above example you could use {{external.title}} inside of your content to load the content sunt aut facere repellat provident occaecati excepturi optio reprehenderit as per the following screenshot:

vero.external-attributes-preview

Adding headers to your API requests

The External Data section supports adding multiple headers to the API requests Vero makes on your behalf.

Headers are stored securely so can be used to store API keys and tokens used to authenticate API requests.

Fusion external attributes headers

Using Liquid merge tags and filters

Fetch HTML content

Liquid is the templating language used by Vero to dynamically insert data in your outgoing messages. We've built a custom "filter" using the Liquid templating language. A filter is essentially a "function".

The fetch_html filter allows you to make API requests that return custom HTML. You can also pass data stored in Vero to your server so that you can use it to manipulate and customize the HTML content you return. HTML that is returned is inserted into your email directly where the fetch_html tag is used.

{% raw %}
  {% fetch_html 'https://www.domain.com/endpoint' %}
{% endraw %}

In the example below, we pass data store in Vero along with the API request. This data can then be used by your server!

{% raw %}
	{% fetch_html 'https://www.domain.com?param={{user.id}}&param2={{event.number_of_widgets}}' %}
{% endraw %}

You should of course replace the domain in this example with whatever URL you prefer. This URL should return raw HTML that will be dumped into the body of your HTML campaign exactly as it is returned.

Here is how you might insert this code into the body of your email: vero.fetch-html

This would then be replaced with the correct HTML upon sending.

Fetch JSON data

The fetch_json liquid filter works in a similar way as the fetch_html filter above but expects a JSON response (instead of a HTML response).

For example, the following Liquid code assigns the JSOn response from your API endpoint to the variable product:

{% raw %}
	{% fetch_json product = 'https://www.domain.com/products/{{user.favourite_product_id}}' %}
{% endraw %}

After adding this to your template or email body you can then access the returned data using the product Liquid variable. In this example our JSON response contains a key called product_name that we can use to print the name of the product.

{% raw %}
	{{json.product_name}}
{% endraw %}

Response codes and retries

Fusion expects to receive a 200 response code in order to send emails.

If a Fusion request receives a 204 response, it will not retry the request and Vero will discard the email immediately. This can be used to tell email to discard certain emails to customers, or to prevent Vero from retrying a failed request. For example, if you didn't want Vero to retry requests, you could develop your API to catch errors and return a 204 in the event of any failure.

If a Fusion request receives anything other than a 200 or 204 response code, it will continue to retry the request up to five times.

Note: Vero retries emails with failed Fusion requests at increasing intervals. If your endpoint continues to return non-`200` response codes, the fifth attempt could be several hours after the initial request was made.

Authentication

Fusion supports basic HTTP authentication or authentication using headers.

For basic HTTP authentication, add details to your URL using the format https://username:password@yoururl.com/data-feed.json. This is supported by both the Liquid fetch_html and fetch_json and the External Data methods.

Headers support any valid header-based authentication method. Headers are encrypted when stored. Read more in Adding headers to your API requests section above.


Fusion is an advanced feature. Please get in touch with our support team via email so we can show you it in action.

Authors

  • Reba Moyes
    Head of Customer Success