Emarsys

Emarsys platform helps marketers deliver personalized, 1:1 experiences across multiple channels and drive business outcomes.

Setup

You will need your username, usually in the format of account_name00X where X is a digit, and the API secret.

To get the API secret, you can create a new API user for Hightouch under Admin > Security Settings.

You will need to enable the necessary endpoints for this API key. For reference, here are the endpoints Hightouch will use in any given sync.

You can select all of these endpoints or you can specify specific endpoints that only your sync will need. For example, if you do not plan on removing contacts when data leave your warehouse, you do not have to select the contact.delete endpoint. Generally, it's easy and safe to select all contacts, fields, and contact lists endpoints.

API users and permissions are described in the Emarsys docs.

Syncing

Hightouch supports syncing contacts and contact lists.

Sync modes

Here are the possible modes for the Emarsys contacts:

• Upsert: pushes new contacts to Emarsys and updates existing contacts with the fields that change in your warehouse.
• Update: updates particular fields on existing contacts in Emarsys. It doesn't add new objects.

This integration also supports Segment mode. New users will be inserted into the list. Users that are removed from the model will be removed from the list.

Record matching

Records can be matched from your source to Emarsys by any default and custom fields. However, it's important to make sure that the field you are using is unique to ensure the best results. For example, Emarsys will throw an error if it detects duplicate values in an attempt to update or remove a batch of contacts. We recommend using email or creating a custom unique field, like an external_id (make sure to set it as unique).

Fields mapping

You can also map to any updatable fields in Emarsys, including your custom fields.

However, there are some things to keep in mind:

• The Emarsys API uses the field's ID when making requests so if you need to use the JSON editor, you will not see any named fields. Instead, you will only see the field ids. You can use this table to cross reference the field ids. You can also view your settings to reference your custom fields.
• Any fields with a date type are formatted: YYYY-MM-DD. You can have your date values be a string in this format (for example, "2020-11-30").
• You must use the Emarsys accepted values for any choice fields (that is, gender, title, etc.).

Debugging

Similarly to the fields mapping in the sync configuration, the request will only show the fields' ids unless it's Emarsys' internal id and uid. Please refer to this table and your custom fields settings to cross reference the ID to the field's name.

The Emarsys API lets us upsert/update/remove contacts in batches per API call. Most cases, the API will let us know which specific rows fail, instead of failing the entire batch. However, the error message may not be very descriptive but it will reference their internal error code.