External data sources

Important

The information below covers the new email design studio. To see how external data works in the classic email editor, go here.

External data sources allow you to import custom real-time information from your own systems into Engage. This data can then be accessed and used when creating email send-outs in the email design studio.

For this to work the following is needed:

A public REST API endpoint
The endpoint accessible by a GET method
A JSON payload being returned
API authorization (optional)

External data will be fetched for each send-out batch in Engage and it may differ from contact to contact based on their marketing group. It cannot be used for retrieving personal data.

Configuration of external data sources is done in the Configure Engage area of your Engage UI.

Configuration

Here are the settings in the configuration of an external data source:

Name: This is the name that will be shown in the email design studio, allowing this data source to be selected there and the data from it to be used.

Unique ID: The internal name of the data source (lower case with underscore). This must be unique. An error will be shown if you try to save an external data source using a name that's already in use by another data source.

URL: This is the URL to the endpoint that returns the JSON data of the data source. The URL can be static or include parameters defined by {name}, as shown in the second example here. The parameters specified in the URL must be defined in the input schema (see below).

https://yourdomain.com/api-endpoint

https://yourdomain.com/api-endpoint/{Site}/?id={ProductIds}

Authorization: Choose "None" or "API key" here (which reveals the following two fields).

Header key: Enter the name of the authorization key, for example "api-key".

Value: Enter the key secret.

Cache time in seconds: How long Engage will cache the response. Enter 0 here if you don't need it to be cached.

There are three fields concerning JSON schema:

Input JSON schema: These are the values that will be displayed in the email design studio when you select this external data source. The properties shown here ("Numberof", "Range", "Sortorder" etc.) must match those in the output JSON for this data source. The required properties are defined at the bottom. Example:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "Site": {
        "title": "Website language",
            "type": "string"
        },
        "Numberof": {
            "title": "Number of products",
            "type": "integer",
            "minimum": 1,
            "maximum": 5
        },
        "Range": {
            "title": "Range",
            "type": "number",
            "minimum": 0.1,
            "maximum": 9.9
        },
        "Sortorder": {
            "title": "Sort order",
            "enum": [
                "lowestprice",
                "highestprice"
            ],
            "type": [
                "string"
            ]
        },
        "Productids": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    },
    "required": [
        "Productids", 
        "Sortorder"
    ]
}

Data type	In the URL	In design studio
string	String	String input
integer	integer string	Number input
number	Number as string	Number input
enum	Enum as string	Single select
array	Comma separated strings	Multi string input

In the case of the JSON given above, the design studio would show the following in the UI (but with empty values in the fields):

Output JSON schema: This JSON informs the system of the form of the payload that is expected from the URL. The properties listed here can then be used in your email layout for personalization, repeaters and display conditions. Example:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "productList": {
      "title": "Product List",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "itemNumber": {
            "title": "Article number",
            "type": "string",
          },
          "imageUrl": {
            "title": "Image url",
            "type": "string",
          },
          "link": {
            "title": "Link url",
            "type": "string",
          },
          "name": {
            "title": "Product title",
            "type": "string",
          },
          "leftinstock": {
            "title": "Number in stock",
            "type": "integer"
          },
          "releasedate": {
            "title": "Release date",
            "type": "string",
            "format": "date",
          },
          "oncampaign": {
            "title": "Ongoing campaign",
            "type": "boolean",
          },
       },
        "required": [
          "itemNumber",
          "imageUrl",
          "link",
          "name"
        ]
      }
    }
  }
}

Sample JSON payload: Mostly as reference, you can add an example payload here.

Warning

Be careful with required properties. If any of them are missing in the payload, the data will not be valid according to the schema and will not be not sent to the design studio.

Data shown in design studio

The properties from the Output JSON schema can be used in your email layout in various ways:

For personalization: For example, you could add a personalized field for "leftinstock" to a text and one for "link" to a button in an email since these are properties returned from the data source.