Using the External Content requires setting up a connection between Emarsys and your API.
Preparation
When planning your External Content connections, consider the following:
- External Content connections are used to differentiate between your API endpoints
- You can create multiple External Content connections for the same endpoint with different set of reference fields.
Before starting the setup and the personalization procedure, it is strongly recommended to read Before you start personalizing with External Content to get a better understanding of the product.
Setting up the External Content connection
The External Content connection can be configured under Content > External Content, where all configured connections are listed.
1. Enter a name for your External Content connection.
This name will be referenced by personalization tokens. Therefore, it is recommended to create descriptive names that represent the use of the connection.
API connection names must start with a letter and may only contain the following characters:
- Lowercase letters (a-z)
- Uppercase letters (A-Z)
- Numbers (0-9)
- Underscores (_)
2. Enter your API URL which will be queried by External Content.
This must be a valid URL.
Example: https://customer.com/api/personal-image-generator
3. Select your authentication method and enter your credentials.
- The following authentication methods are supported:
- Basic HTTP authentication - You need to specify your API's Username and Password.
-
OAuth2 - External Content supports the OAuth2 Client Credential grant. You need to specify the following parameters:
- URL - External Content uses this URL to request an access token.
- Client ID
- Client secret
-
Scope (optional) - Your service can support different scopes for the client credentials grant. This can limit the types of data accessible to Emarsys.
For more information on scopes, see the OAuth 2.0 website.
4. Enter your reference fields.
Reference fields are the key for External Content for pairing contact specific data on the customer side to contacts in the Emarsys database. A Reference field has to contain a value present in your data. To use the reference fields for personalization, you have to specify how the personalization service should use them during preset creation.
For more information on the reference fields and their use, see Creating External Content tokens.
Reference field names must start with a letter and may only contain the following characters:
- Lowercase letters (a-z)
- Uppercase letters (A-Z)
- Numbers (0-9)
- Underscores (_)
The following case requires a single reference field.
Let’s assume that you use only internal client IDs to identify your customers in your database instead of email addresses. If the Emarsys database of your account also contains your unique client IDs next to email addresses, use this as a reference field.
Based on this, during personalisation preset creation you will be able to match the data stored in the row of your client IDs to your individual contacts.
Multiple reference fields can also be specified. This is needed when you would like to filter your results with criteria requiring a combination of filters.
Let’s assume that you have a service which can create images based on the season personalized with the age and gender of your customer.
(Seasonal background with a younger or older male or female figure and a salutation.) The url of this image is stored together with your contacts in your service. Each age group has four images prepared for each season, however, you want to send only the current.
After setting the season (a constant value for everyone), gender (constant) and date of birth (contact field) reference fields, and the image URL response field, your API can return a response with the URL to be used in a personalization token.
Reference fields are called parameters in the Test Results box and in the Create External Content Preset window.
5. Enter your Response Fields.
Response fields specify which JSON fields are expected in the response. The content of these fields is used for personalization.
Response field names must start with a letter and may only contain the following characters:
- Lowercase letters (a-z)
- Uppercase letters (A-Z)
- Numbers (0-9)
- Dashes (-)
- Underscores (_)
A single response field is enough to return a single unique value.
For example, your service can respond with the image URL of a specific contact’s avatar.
In an External Content connection, Multiple response fields can also be specified.
Let’s assume that you have a service that can calculate product recommendations for your contacts. In this case, the following fields can be useful to construct the recommendation in a Emarsys message:
- Product name (name)
- Price (price)
- Discount percentage (discount)
- Webshop product URL (url)
- Index image URL (small_img_url)
6. Enter values for testing. Click Test to try out your connection.
Use valid values that are present in your database. You can see the detailed request and response on the right side, so if an issue occurs you will be able to easily debug what went wrong.
Error messages in responses have to be added by the customer when they develop their API.
7. Click Save, to save your connection. This action also tests your connection.