> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Emarsys

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

> [!NOTE]
>
> Emarsys is a [premium destination](https://docs.hightouch.com/pricing/ss-pricing.md#premium-destinations) and is only available on [Business tier plans](https://hightouch.com/pricing).

## Setup

Hightouch supports two ways to authenticate with Emarsys:

* **OpenID Connect** (recommended): uses a client ID and client secret with the Emarsys v3 API.
* **WSSE**: uses a username and API secret with the Emarsys v2 API. Emarsys is retiring WSSE authentication. It stops supporting WSSE on February 1, 2027, and may turn off WSSE-based APIs at any time after that date.

> [!WARNING]
>
> If your Emarsys destination uses WSSE, switch it to OpenID Connect before
> February 1, 2027. Create OpenID Connect credentials as described below, then
> open your destination's **Configuration** tab, select **Use OpenID Connect
> (recommended)**, enter the client ID and client secret, and save. Your
> existing syncs keep working without any other changes.

### OpenID Connect

An Emarsys account owner can create OpenID Connect API credentials under **Management** > **Security Settings**. Copy the client ID and client secret into Hightouch.

> [!WARNING]
>
> Emarsys only displays the client secret once, when you create the credentials.
> Save it before you leave the page.

OpenID Connect credentials always use the default Emarsys API host, `api.emarsys.net`, even if your account is on a regional instance.

### WSSE

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 **Management** > **Security Settings**.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-emarsys-api-settings.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=39813bdbfa0d3073deb2671d80600a8f)

> [!WARNING]
>
> Make sure to copy and save the secret key here since the entire key will no
> longer display after you close the confirmation dialog box.

If your Emarsys account is on a regional instance, enter its API host (for example, `suite6.emarsys.net`) in the **API host** field. Leave it blank to use the default, `api.emarsys.net`.

### Endpoint permissions

Whichever authentication method you use, you need to enable the necessary endpoints for your API credentials. The endpoints
Hightouch requires depend on how you configure your syncs.

#### Always required

* [`field.get`](https://dev.emarsys.com/docs/core-api-reference/a0l7f9tviiuiv-list-available-fields) — Used during the connection test and to load available contact fields for mapping. Without this endpoint enabled, the connection test will fail with a 403 error.

#### Contact syncs

* [`contact.create`](https://dev.emarsys.com/docs/core-api-reference/g617t4kfs4y69-create-contact) — Required for upsert sync mode (creates new contacts).
* [`contact.update`](https://dev.emarsys.com/docs/core-api-reference/f8ljhut3ac2i1-update-contacts) — Required for upsert and update sync modes.
* [`contact.delete`](https://dev.emarsys.com/docs/core-api-reference/szmq945esac90-delete-contacts) — Only required if you plan to remove contacts when data leave your warehouse.

#### Contact list syncs

* [`contactlist.list`](https://dev.emarsys.com/docs/core-api-reference/paz2wputeebqx-list-contact-lists) — Required to load available contact lists for selection.
* [`contactlist.contact.add`](https://dev.emarsys.com/docs/core-api-reference/1m0m70hy3tuov-add-contacts-to-a-contact-list) — Required to add contacts to a list.
* [`contactlist.contact.delete`](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4MzI-remove-contacts-from-a-contact-list) — Only required if you plan to remove contacts from a list.
* [`contactlist.create`](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4MjI-create-a-contact-list) — Only required if you plan to create new contact lists from Hightouch.

The following screenshot shows an example of a working permissions configuration in the Emarsys UI.
It is also safe to enable all **contacts**, **fields**, and **contact lists** endpoints.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/emarsys/emarsys-permissions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=392e43891545712c907651f86c7e1659)

API users and permissions are described in the [Emarsys docs](https://dev.emarsys.com/docs/core-api-reference/ef41493bd7812-endpoint-permission-settings).

## 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.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-emarsys-segment-mode.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4dd10205247c45c99cd07bb2bb2bec51)

### 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*).

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-emarsys-record-matching.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a456e318b7f5e132470250005e9be035)

### Fields mapping

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

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-emarsys-fields.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=cc53fbaca118ec7c63726c5e967f50e3)

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](https://dev.emarsys.com/docs/emarsys-api/ZG9jOjI0ODk5NzY3-contact-system-fields) 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](https://dev.emarsys.com/docs/emarsys-api/ZG9jOjI0ODk5NzY3-contact-system-fields) and your custom fields settings to cross reference
the ID to the field's name.

![](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-emarsys-request.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4162da665d40a549355ca75de5841240)

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](https://dev.emarsys.com/docs/emarsys-api/ZG9jOjI0ODk5NzY4-http-200-errors).

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).