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

# Salesforce Marketing Cloud

> Personalize campaigns in Salesforce Marketing Cloud with rich customer data from your data warehouse

> [!NOTE]
>
> Salesforce Marketing Cloud 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).

# Overview

Salesforce Marketing Cloud (SFMC) is a digital marketing platform that enables businesses to create personalized customer journeys across email, mobile, social, web, and more. This integration allows you to sync your data from Hightouch to SFMC to power personalized marketing campaigns, manage contact data, automate customer journeys, and trigger communications.

With the Hightouch SFMC integration, you can:

* Sync data to SFMC Data Extensions for segmentation and personalization
* Update contact information for better targeting
* Manage entry and exit from customer journeys based on your data
* Trigger email and SMS messages based on customer behaviors

This documentation will guide you through setting up the connection, configuring syncs, and troubleshooting common issues.

## Supported syncing

| Sync Type | Description | Supported Sync Modes | API Reference |
| :- | :- | :- | :- |
| [**Data Extensions**](#data-extensions) | Sync records to new or existing Data Extensions, using the SOAP API and optionally file uploads | Upsert, Mirror | [Manage Data Extensions ↗](https://help.salesforce.com/s/articleView?id=sf.mc_co_salesforce_data_extensions.htm\&language=en_US\&type=5) |
| [**Contacts**](#contacts) | Sync records to Marketing Cloud contacts | Upsert | [Manage SOAP API objects ↗](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/soap_web_service_objects.html) |
| [**Journeys**](#journeys) | Trigger API events to enter and exit contacts from journeys as they're added to and removed from your query result | Add, Remove | [Fire entry events ↗](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/how-to-fire-an-event.html?q=entry) and [exit contacts ↗](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/contactExitRequest.html) |
| [**Triggered send**](#triggered-send) | Send email and SMS messages to individual subscribers | Trigger | [Create triggered sends ↗](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/creating_a_triggered_send_using_the_async_api.html) |

## Salesforce Marketing Cloud setup

Before you connect Hightouch to Salesforce Marketing Cloud (SFMC), you need to create an installed package in SFMC for Hightouch to use.

If you want to sync records to Data Extensions using [either mirror mode or upsert mode with file uploads](#data-extensions), you also need to [create an FTP user](#create-ftp-user).

### Create installed package in SFMC

1. Log in to your SFMC instance. Go to **Setup**.

![Opening Setup in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-setup.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0082fd08ff86f68cfc28307d1a9eb16a)

2. In the left sidebar, go to **Apps → Installed Packages** and click **New**.

![Package creation in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-new-package.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=18b4ccab9bda03f79168ac33e18d37e2)

3. Name your package, for example, "Hightouch Integration." Optionally provide a description, and click **Save**.

![Package creation in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-new-package-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e797bce9e0316bfe829104975a617576)

4. Click **Add Component** and select **API Integration** as the component type. Click **Next**.

![Package configuration in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-add-component.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b513ec995322e64ba746f2d4330744ba)

5. Select **Server-to-Server** as the integration type and click **Next**.

![Package configuration in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-add-component-type.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=7e54a04c0db3fb3f8e967d877a1997c7)

#### Permissions

These are the minimum scopes for syncing to Contacts, Journeys, and Data Extensions.

> [!NOTE]
>
> Carefully select the appropriate permissions based on your specific use case.

* **Automation > Journeys**: Read, Write, Execute, Activate/Stop/Pause/Resume/Send/Schedule
* **Contacts > List and subscribers**: Read, Write
* **Data > Data Extensions**: Read, Write
* **Provisioning > Accounts**: Read

![Package configuration in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-automation-scope.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=7df98926a9c3d7fc0dcf6c01b51718dc)

If you want to sync to [Data Extensions](#data-extensions) using mirror mode or upsert mode with
[file uploads](#automatic-file-import-via-file-uploads), grant these additional permissions:

* **Data > File Locations**: Read, Write
* **Automation > Automations**: Read, Write, Execute

If you want to trigger sends, grant these additional permissions:

* **Channels > Email**: Read
* **Channels > SMS**: Read

If you would like to grant a custom subset of scopes for just the SFMC
features you want to use, see the section on [custom scopes](#custom-scopes).

Once you save your permissions, you should see a new API Integration component in your package.

With the API Integration created, copy the **Client ID**, **Client Secret**, and subdomain to enter into Hightouch.

> [!TIP]
>
> The subdomain is the part of the **Authentication base URI** after `https://`
> and before `.auth.marketingcloudapis.com/`. For example, if your
> Authentication base URI is
> `https://mc6vgk-yfjd8879pq4v.auth.marketingcloudapis.com/`, your subdomain is
> `mc6vgk-yfjd8879pq4v`.

![Package configuration in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-base-uri.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=74209f5e5549e64687d0f66487b949ef)

### Create FTP user

> [!TIP]
>
> You only need to create a FTP user if want to sync [Data
> Extensions](#data-extensions) via file uploads. Using File Upload mode can
> optimize sync performance, especially on high volume syncs (over 1 million
> records). Learn more about how file upload protocol works and its tradeoffs in
> the [file uploads section](#automatic-file-import-via-file-uploads). You will
> need a SFMC FTP user even if you are using a blob storage file location.

> [!WARNING]
>
> If your SFMC instance has parent-child Business Units and you want to sync to
> a child Business Unit using FTP, you must create the FTP user in the child
> Business Unit. Creating the FTP user in the parent Business Unit will not work
> for syncing to child Business Units.

1. In your SFMC instance, go to **Setup → Administration → Data Management → FTP Accounts** and click **Create User**.

![FTP User creation in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-new-sftp-user.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1f64a68e3b2b2256ed751876ddb88831)

2. By default, the **FTP Username** is your [Marketing Cloud Member ID (MID)](https://trailhead.salesforce.com/content/learn/modules/marketing-cloud-developer-basics/learn-administration-basics), including the current parent account or child business unit. You can keep the default value.

3. Enter an **Email Address** for the new FTP user. This can be the email account you use to log in to SFMC or another one. You won't need this address to connect to Hightouch.

4. Enter a **Password** for the user. Password complexity requirements combine Marketing Cloud password policy and server-side FTP password requirements. These policies require a minimum of 12 characters and no reuse of the five most recent passwords. Reenter the password in **Repeat Password**.

5. The next screen prompts you to choose your authentication method.

   * If you want to use a password, keep this selection.

     ![FTP User creation in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-new-sftp-user-authentication-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=3dc181276a4c0fa01cf46f07f8048982)

   * If you want to authenticate Hightouch to SFMC using an SSH key, select **SSH Key**. Follow [SFMC's instructions](https://help.salesforce.com/s/articleView?id=sf.mc_overview_key_create_ssh_for_ftp.htm\&type=5) for how to add a key. Enter the public key into the SFMC and keep the private key for when you [connect to Hightouch](#connect-to-sfmc).

     ![FTP User creation in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-new-sftp-user-authentication-3.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=561552912a4b761106d83a3d0c6b5267)

6. On the next screen, select permissions for your FTP user. At a minimum, provide the user **Upload** access to the **Import** directory.

![FTP permissions in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-ftp-permissions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=73b19872b15ec1c6586f65d5deabedad)

7. Allowlisting IP addresses is optional. For additional security, you can enter [Hightouch's IP addresses](https://docs.hightouch.com/security/networking#ip-addresses). Click **Next**.
8. Select a **Home Folder**. We recommend setting the home folder to the root directory. If you choose to specify a restricted scope, ensure that this FTP user has access to the **Import** directory.

![FTP home folder in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-ftp-home-folder.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1ec493a0d0e73f412a5e2969bde9ef4e)

9. Make sure to copy your FTP Username and either password or SSH private key for entry into Hightouch. Click **Save**.

## Connect to SFMC

You can now connect SFMC to Hightouch. Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button.
Select **Salesforce Marketing Cloud** and click **Continue**.

### Authentication

You can authenticate Hightouch to SFMC by entering the **Client ID**, **Client Secret**, and **Subdomain** you copied during [package creation](#create-installed-package-in-sfmc).

> [!TIP]
>
> The subdomain is the part of the **Authentication base URI** after `https://`
> and before `.auth.marketingcloudapis.com/`. For example, if your
> Authentication base URI is
> `https://mc6vgk-y5h9sgf6c5t8vxs09pq4v.auth.marketingcloudapis.com/`, your
> subdomain is `mc6vgk-y5h9sgf6c5t8vxs09pq4v`.

### Client secret rotation

> [!WARNING]
>
> SFMC client secrets expire 180 days after they're generated, and Salesforce
> has announced that all client secrets created before this policy took effect
> expire on September 30, 2026. When your secret expires, all syncs to this
> destination fail with an `invalid_client` authentication error until you
> rotate the secret. See [Salesforce's rotation
> guide](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rotate-oauth2-secret.html)
> for details.

Salesforce doesn't provide an API for rotating client secrets, so you must rotate them in the SFMC interface. SFMC accepts both the staged and the active secret until you activate the staged one, so you can rotate without downtime:

1. In SFMC, go to **Setup → Apps → Installed Packages** and open the package Hightouch uses. In the **Staged Secret** section, select **Generate**.
2. In Hightouch, enter the new secret in the **Client Secret** field in the [destination's configuration](https://app.hightouch.com/destinations?from=docs).
3. In SFMC, select **Activate** on the staged secret.

To see expiration dates for all of your client secrets, check the summary table on the **Installed Packages** page in SFMC Setup.

### FTP credentials

> [!NOTE]
>
> This section is only required if you want to [sync records to Data Extensions
> using mirror mode or upsert mode with file
> uploads](#automatic-file-import-via-file-uploads).

Enter your FTP user credentials:

* **FTP Username**: typically a numeric Marketing Cloud MID
* **Password** *or* **private key**
  * To use a private key, you must have [uploaded the corresponding public key in SFMC](#create-ftp-user)
  * If using a private key, you must enter the complete private key, starting with `-----BEGIN...PRIVATE KEY-----`.
  * If your private key requires a passphrase, enter it as well

> [!WARNING]
>
> Incorrect FTP credentials will cause file upload syncs to fail. Double-check
> your credentials if you encounter connection issues.

### File location

> [!TIP]
>
> You only need to set up a file location in SFMC if you are syncing Data
> Extensions with file uploads.

Hightouch supports the following file location types:

* ExactTarget Enhanced FTP Import Directory (default)
* Relative Location under FTP Site
* Google Cloud Storage
* Amazon S3

#### ExactTarget Enhanced FTP Import Directory

For **ExactTarget Enhanced FTP**, if you have chosen a different External Key for this location, enter the External Key to ensure Hightouch is able to access the uploaded files.

![ExactTarget Enhanced FTP - File Location External Key](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-exacttarget-enhanced-ftp-file-location.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=743d713b2a3692c4907d25587fa523ee)

#### Relative Location under FTP Site

For **Relative Location under FTP Site**, enter the Relative Folder Path and the External Key to ensure Hightouch is able to access the uploaded files.

![Relative Location under FTP Site - File Location and External Key](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-relative-location-for-ftp-site-file-location.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=3321002b7c751978334570c87fc1eaf7)

> [!TIP]
>
> If your FTP user has a Home Folder other than the root directory, enter the
> file location relative to the FTP user's home folder in your Hightouch
> destination configuration.

#### Google Cloud Storage

To use the Google Cloud Storage file location in SFMC you will need:

* Google Cloud Storage bucket
* Google Service Account with **read** access to your bucket. This will be used by SFMC to read from your bucket.
* Google Service Account with **write** access to your bucket. This will be used by Hightouch to upload files.

If you do not have a Google Service Account, you can follow the setup instructions in our [Google Cloud Platform (GCP) documentation](https://docs.hightouch.com/security/gcp.md).

To set up a Google Cloud Storage file location in SFMC:

1. Go to **Setup → Data Management → File Locations** and create a new file location.
2. Configure your file location's name and external key.
3. Choose Google Cloud Storage for Location Type.
4. Enter your GCS bucket name.
5. If you would like for files to be uploaded to a specific path in your bucket, enter the path as the **Relative Location** in your file location.
6. Upload your Google Service Account credentials. Ensure that at a minimum this role has read access to your bucket.

![Google Cloud Storage file location setup](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-gcs-file-location.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=49596ece4975a0611c6f1bce38059f3f)

In Hightouch, select the Cloud Credentials you'd like to use to write to your bucket. Ensure this account has write access to your bucket.
Enter your file location External Key, GCP project ID, bucket name, and relative path.

![Google Cloud Storage file location in Hightouch](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-gcs-file-location-form.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=ea8a6dc2f260dc99b370a1f1a52b6991)

Test your connection to ensure you've successfully connected to SFMC's API, FTP, and your GCS bucket.

#### Amazon S3

To use the Amazon S3 file location in SFMC you will need:

* Amazon S3 bucket
* AWS Credentials with **read** access to your bucket. This will be used by SFMC to read from your bucket.
* AWS Credentials with **write** access to your bucket. This will be used by Hightouch to upload files.

If you do not have AWS Credentials, you can follow the setup instructions in our [AWS documentation](https://docs.hightouch.com/security/aws.md).

To set up an AWS S3 file location in SFMC:

1. Go to **Setup → Data Management → File Locations** and create a new file location.
2. Configure your file location's name and external key.
3. Choose Amazon Simple Storage Service for Location Type.
4. Choose whether you'd like to authenticate with an Access Key or Access Key with IAM role and enter your AWS credentials. Ensure that at a minimum this account has read access to your bucket.
5. Enter your S3 bucket name.
6. If you would like for files to be uploaded to a specific path in your bucket, enter the path as the **AWS Relative Location** in your file location.

![Amazon S3 file location setup](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-s3-file-location.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=5a8f3f2aeadf2582518f7c72c67ea9d9)

In Hightouch, select the Cloud Credentials you'd like to use to write to your bucket. Ensure this account has write access to your bucket.
Enter your file location External Key, AWS region, bucket name, and relative path.

![Amazon S3 file location in Hightouch](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-s3-file-location-form.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=361308b150e3f894736a78e34277c139)

Test your connection to ensure you've successfully connected to SFMC's API, FTP, and your S3 bucket.

### Custom scopes

> [!TIP]
>
> This section is for advanced users who need specific permission scopes for
> their integration.

By default, Hightouch requests permission for Journeys, Contacts, and Data
Extensions. If you want to use a subset of these features, you can grant a
custom subset of scopes in your SFMC package. After you do this, enter a
space-separated list of scopes in the **Custom scopes** field in the
Hightouch destination configuration.

For example, if you want to sync to Data Extensions via the SOAP API, you
can grant the following scopes in your SFMC package:

* **Data > Data Extensions**: Read, Write
* **Provisioning > Accounts**: Read

Then, enter the following scopes in the Hightouch destination configuration:

```
accounts_read data_extensions_read data_extensions_write
```

![Custom scopes in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-custom-scopes.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=3fa3bb44373e17668ee52c734883568f)

See the [SFMC docs for a full list of
scopes](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_rest_permission_scopes/rest-permissions-and-scopes.html).

> [!WARNING]
>
> The scopes listed in Hightouch can't exceed the scopes granted in your SFMC
> package. If you attempt to use scopes not granted in SFMC, your authentication
> will fail.

If you import SFMC email templates through Context Hub, template import also requests only the scopes in **Custom scopes**. Add `email_read` and `documents_and_images_read` to the field, after you grant them in your SFMC package.

### Allowed Business Units

> [!TIP]
>
> This section is relevant for SFMC instances with multiple Business Units.

By default, Hightouch can access all Business Units in your SFMC instance that
have the installed package enabled. If you want to restrict access to a subset
of Business Units, you can enter a space-separated list of Business Unit IDs in
the **Allowed business unit IDs** field in the Hightouch destination
configuration.

You can find the Business Unit ID, or MID, by clicking on the account dropdown at
the top of the SFMC console.

![Finding MID in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-mid.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b7f761df7c8694115adffbd5ab3f9af4)

## Use SFMC with agents

Agents can read the campaigns, journeys, and email content you've built in SFMC when you connect SFMC in **Context Hub > Connected data**. Context Hub uses the credentials from this destination, so you don't enter them again.

The installed package needs more read permissions for this than syncing does. For the full list, see Connect advertising and lifecycle platforms. If the package is missing a permission, connecting fails with a [`scope_mismatch` error](#scope_mismatch-when-reading-campaigns-or-templates).

## Sync configuration

Once you've set up your Salesforce Marketing Cloud destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and the Salesforce Marketing Cloud destination you want to sync to.

The following sections outline the different types of syncs you can configure with SFMC:

### Data Extensions

Hightouch supports syncing objects to existing Data Extensions and creating new ones.
You can select either **Upsert** or **Mirror** mode.

* In **Upsert** mode, you can choose whether to use the SOAP API or [file uploads](#automatic-file-import-via-file-uploads). Hightouch inserts new objects into the Data Extension and keeps all mapped object attributes up-to-date.
* In **Mirror** mode, you can't select between SOAP API or file uploads. Hightouch always uses file uploads, SOAP, and an Overwrite import automation in SFMC to overwrite the entire Data Extension with your model's query results.

#### Optional configurations

You can optionally choose which **Business Unit** and which **Data Folder** you would you like to sync data to. If you leave these configuration empty, Hightouch uses the defaults configured in SFMC.

![Data extension configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-optional-configurations.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d1e72bc146033c099088212a50b6d205)

#### Automatic Data Extension creation

You can optionally choose whether Hightouch should **automatically create a Data Extension**. If you enable automatic creation, Hightouch creates a Data Extension the first time the sync runs. It doesn't create new Data Extensions on subsequent runs. If you add columns to the sync config, Hightouch automatically adds them to the Data Extension.

![Data extension configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-data-extension-auto-creation.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=83179edc719720fb7b41cd65bda0d658)

When creating a new extension, you can optionally specify the Data Extension's name.
If you leave the name blank, Hightouch uses the model name.
The name also becomes the Data Extension's **customer key**.

You can include timestamp variables in the Data Extension name, surrounding each with `{}`.
Hightouch supports these timestamp variables:

* `YYYY`: Represents the full year in four digits.
* `YY`: The last two digits of the year.
* `MM`: Two-digit month format (01-12).
* `DD`: Two-digit day format (01-31).
* `HH`: Two-digit hour format in 24-hour clock (00-23).
* `mm`: Two-digit minute format (00-59).
* `ss`: Two-digit second format (00-59).
* `ms`: Three-digit millisecond format.
* `X`: Unix timestamp in seconds.
* `x`: Unix timestamp in milliseconds.

All dates and times are UTC.

You can also use other [variable values](https://docs.hightouch.com/syncs/mapping-data.md#variable-values) to include sync metadata in the Data Extension name:

* `{model.id}`
* `{model.name}`
* `{sync.id}`
* `{sync.run.id}`

To change the name or customer key, you need to create a new sync. Hightouch doesn't modify the Data Extension's name or customer key after the first run.

> [!TIP]
>
> You can also optionally enter a file path when creating a Data Extension, such
> as `path/to/dataExtension`. If you choose a file path that includes folders,
> Hightouch will only create new folders if they do not already exist, relative
> to the selected folder in the Data Folder option. This path can also include
> the variable values mentioned above, such as `{YYYY}/{MM}/{DD}/{model.name}`.

#### Automatic file import via file uploads

By default, Hightouch uses the SOAP API to sync Data Extension options in upsert mode. If you select to use File Upload mode, Hightouch uploads records via file transfer to SFMC, which may lead to better sync performance. While using File Upload mode is generally faster, it provides less visibility into individual records' sync successes and failures.

Generally, blob storage file locations (such as Google Cloud Storage and Amazon S3) are more performant file servers than SFMC's default option of ExactTarget Enhanced FTP server.

To use File Upload mode, ensure:

* your SFMC package has [the appropriate scopes](#create-a-server-to-server-package)
* you've [created an FTP user](#create-ftp-user) in SFMC
* you've [authenticated the FTP user](#connect-to-sfmc) in your destination configuration

Additionally, if you are using a blob storage file location, ensure:

* your SFMC file location has read access to your bucket
* the credentials you've provided Hightouch has write access to your bucket.

When using File Upload mode, Hightouch creates and runs an [import definition](https://help.salesforce.com/s/articleView?id=sf.mc_es_import_activity.htm\&type=5) to load the data into the Data Extension. By default, Hightouch includes 100,000 rows in each file. You can configure this batch size in the Hightouch UI—the maximum value is 10 million rows per file. After each batch, Hightouch processes the SFMC results file to determine row errors.

> [!NOTE]
>
> SFMC provides more detailed error responses when using the SOAP API. If you
> need to debug errors and the error messages from File Upload mode aren't
> helpful, we recommend trying the SOAP API.

> [!WARNING]
>
> If you enable [deletion](#delete-behavior) in upsert mode, Hightouch removes
> deleted rows in the Data Extension using the [SOAP
> API](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/delete.htm),
> since SFMC doesn't support deletions using FTP directly. If you want to
> completely overwrite the Data Extension with the results of your sync, use
> **Mirror** mode.

#### Record matching

You can match objects from your source to your Data Extension on your Data Extension's [primary key](https://help.salesforce.com/s/articleView?id=000388307\&type=1).
Select the model column that contains these values.

> [!WARNING]
>
> Editing the Data Extension field used for record matching is only possible
> before triggering the first sync run. Otherwise, making this change results in
> an error. If you want to use a different field once the sync has already run,
> you need to create a new sync.

#### Field mapping

You can map any model column to any field in your Data Extension.
Make sure that you map all **non-nullable fields** when syncing new objects to the Data Extension.
A non-nullable field is a field that is required to be populated with a value.
When creating or editing a record in SFMC, if a non-nullable field is left empty, the system won't allow the record to be saved and will return an error message.

You can check which fields are non-nullable fields in SFMC by inspecting your Data Extensions:

1. Open the Email Studio in your SFMC account.

![Inspecting Data Extensions in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-email-extension.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=c5fe5c8af90bdb6ea8bbd3164b37ef27)

2. Select the Data Extension you want to check.

![Inspecting Data Extensions in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-data-extension-inspection.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e56d59f372ae237b997f06147694580f)

3. Inspect the **Fields** section in the Data Extension to see a list of all fields.

![Inspecting Data Extensions in SFMC](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-data-extension-nullable-fields.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=90194689cbea185b6cf1204b33be1de7)

4. Look for the **Nullable** column in the list. This column includes a checkbox for each field.

5. If a field doesn't have a check in the **Nullable** column, it means that the field is non-nullable and must have a value in it when a record is created or updated. Make sure you map all non-nullable fields.

In the example screenshot below, since `email` is the only field without a check in the Nullable column, it is the only non-nullable field.

In **Upsert** mode, you can sync records that don't include all non-nullable fields, but only if the object already exists in the Data Extension.

> [!NOTE]
>
> SFMC requires a minimum of one field mapping when sending data using
> *SOAP*-mode. This can be a placeholder field.

#### Field creation

When creating a new Data Extension with Hightouch, you can create new fields and select their types while field mapping. First enter a field name, then select its type.

![Data extension configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-data-extension-field-creation.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=d7c67c7a39102b3e30758919d32bbabc)

Text and Decimal field types allow for additional configuration.

![Data extension configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-data-extension-field-creation-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=2fda94972bc8ae05d43defad28974b15)

Hightouch adds new fields to the Data Extension on each run but doesn't remove fields that leave the model's query results.

#### Sendable and testable Data Extensions

For auto-created Data Extensions, you can select whether the Data Extension is **sendable** and **testable**.

A sendable Data Extension is a type of Data Extension that can be used to send email messages or other types of communications to subscribers. Sendable Data Extensions are designed to contain subscriber data that can be used in email marketing campaigns, triggered sends, or other types of communications.

A testable Data Extension is used to send test emails or other test communications to a small group of recipients, usually internal stakeholders or quality assurance testers. Testable Data Extensions are designed to mimic the structure of a sendable Data Extension, but with a smaller set of test data.

To be designated as sendable, a Data Extension must meet certain requirements, including:

* It must contain an email address or mobile number field that is marked as the primary sendable field.
* It must contain at least one additional field that is used as a personalization field in the email message.
* It must be mapped to a profile attribute group, which is used to store additional subscriber data that is not included in the sendable Data Extension.

To make the Data Extension you are syncing via Hightouch sendable, select the field to use as the primary sendable field and the field to map to a subscriber field. The options available for the sendable field are [the fields you mapped](#field-mapping-2).

> [!TIP]
>
> The length of the field chosen in send relationships is [limited to 254
> characters](https://help.salesforce.com/s/articleView?id=sf.mc_rn_2024_spring_cab_de_restriction.htm\&type=5).
> Choose the `Text - 254 characters` field type when creating a sendable field
> in Hightouch to enforce this limit.

![Data extension configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-data-extension-sendable.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=376dd8a3c1a79be8e274351a305438a0)

You can only set a Data Extension to be testable once you select it to be sendable.

#### Data Retention Policy

You can set a data retention policy on your Data Extension through Hightouch. Hightouch will **not** edit existing data policies unless explicitly enabled.

You can choose what data should be deleted in your policy:

| Behavior | Description |
| - | - |
| **All records and Data Extension** | All records and the Data Extension will be deleted at the end of your data retention period |
| **All records** | All records will be deleted at the end of your data retention period, but the Data Extension will not be deleted |
| **Individual records** | Records will be deleted from your Data Extension individually as they reach the Data Extension period. The Data Extension will not be deleted. |

You can choose the data retention period in days depending on how long you'd like to store your Data Extension and records.
If you choose to reset the retention policy upon each successful sync run, the data retention period will restart whenever data is successfully imported into your Data Extension.

> [!WARNING]
>
> Data retention policies cannot be removed through Hightouch. To remove an
> existing data retention policy, navigate to your Data Extension in SFMC
> Contact Builder and turn off the data retention policy.

#### Delete behavior

You can choose how to handle Data Extension when the corresponding rows are deleted in your source.

| Behavior | Description |
| - | - |
| **Do nothing** | Keep the object in SFMC |
| **Delete the record** | Remove the SFMC record completely |

#### Concurrency

When syncing to SFMC in File Upload mode, you can configure the concurrency used in the FTP upload to SFMC in Advanced options. Enter a value between 1 and 10.
Higher concurrency values will increase upload speeds, but can cause disruptions when simultaneously running multiple Hightouch syncs to SFMC. For this reason, the default concurrency is 1.

Concurrency options are not available for blob storage file locations.

#### File Retention

By default, Hightouch will delete the CSV files used to populate a Data Extension and the results file from the Import Definition automation from your SFMC FTP server. You can choose to keep files on your SFMC FTP server in Advanced options. Files on the SFMC FTP server will automatically be deleted by SFMC after 21 days.

Files are not automatically deleted from your blob storage file locations. We recommend setting a retention policy on your bucket to avoid storing stale CSV files.

#### Notifications

If you would like to receive an email notification when an Import Definition to your Data Extension succeeds, you can enter an email address in Advanced options.
In Mirror mode, one email will be sent for each sync run. In Upsert mode, one email will be sent for each batch completion. Depending on your batch size, this could be multiple emails per sync run.

#### Triggering automations

In Mirror mode, if you would like to trigger an automation after the completion of your Data Extension sync run, you can select **Yes** or **No** and enter either an **External key** or an **Automation ID**. If **Yes**, an automation will run even if there are failed rows in the sync. If the automation itself fails, the entire sync run is marked as failed.

### Contacts

This integration supports upserting contacts into Marketing Cloud. In upsert mode, Hightouch inserts new users into SFMC and updates [mapped user attributes](#field-mapping) on existing contacts.

#### Record matching

Hightouch matches rows from your model to Marketing Cloud contacts by **Contact Key**. Select the model column that contains these values.

![SFMC Contact sync configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-record-matching.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=155d768489dbe084052d08259d58c768)

> [!TIP]
>
> Contact Keys are different from Contact IDs and email addresses. Check out
> [Salesforce's
> article](https://trailhead.salesforce.com/content/learn/modules/marketing-cloud-contact-management/understand-contacts-and-contact-model-relationships)
> to learn more.

#### Field mapping

You can sync any model columns to Marketing Cloud's contact attributes.

![SFMC Contact sync configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-field-mapping.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=efd4a06bd62d99314d8ab5e84bee2b68)

Ensure all the required fields in each attribute set is completed. For example, to add an email address, be sure to map both **Email Addresses.Email Address** and **Email Addresses.HTML Enabled** fields. Refer to the usage section of SFMC's [Creating Contacts](https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/createContacts.htm) documentation for a list of attribute sets.

### Journeys

Hightouch can manage the entry and exit of contacts in Marketing Cloud journeys based on your model's query results.

* When a record enters your results set, Hightouch adds a contact to the journey via the contact's [Contact Key](https://trailhead.salesforce.com/content/learn/modules/marketing-cloud-contact-management/understand-contacts-and-contact-model-relationships).
* When a record leaves your results set, Hightouch removes the contact from the journey via the contact's [Contact Key](https://trailhead.salesforce.com/content/learn/modules/marketing-cloud-contact-management/understand-contacts-and-contact-model-relationships).

> [!NOTE]
>
> Hightouch does not observe duplicate primary key errors. Adding a record with
> a primary key that already exists in the journey will be marked as successful.
> Similarly, removing a record with a primary key that was already removed from
> the journey will also be marked as successful.

#### Journey selection

Here is an example journey that you could manage with Hightouch:

![SFMC Journey example](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-entry-event.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=293a612a68dc7ebb18f72a4d1228b044)

Note that it's:

* A multistep journey
* Triggered by an entry event with an associated **Data Extension** and **event definition key**

Hightouch automatically looks for the event definition key if you select a journey that fits the preceding requirements.

![Journey selection in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-select-journey.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=8861aff7e898cef7790788a652ff3a01)

#### User identifiers

Hightouch enters and exits contacts from the journey via **Contact Key**. Select the model column that contains these values.

![SFMC Contact sync configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-record-matching.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=155d768489dbe084052d08259d58c768)

> [!TIP]
>
> Contact Keys are different from Contact IDs and email addresses. Check out
> [Salesforce's
> article](https://trailhead.salesforce.com/content/learn/modules/marketing-cloud-contact-management/understand-contacts-and-contact-model-relationships)
> to learn more.

#### Field mapping

You can use field mapping to map any other columns in your query results to the Data Extension containing your journey's data.

![Journey configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-attributes.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=495935f92af9b3bc3530aed5e4cdd427)

The Data Extension requires the **email\_address** field—be sure to map a model column to that attribute. You can do this in Hightouch by typing "email\_address" as a **Field from Salesforce Marketing Cloud** in the mappings section and then selecting the appropriate model column.

![Journey configuration in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-sfmc-map-email.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a3d851a6db51a806a4b68ee5e3e00226)

### Triggered send

Hightouch can trigger emails to individual subscribers via the Marketing Cloud API. This is useful for sending personalized messages to specific users based on their behavior or attributes.

Select an existing Triggered Send definition, then map the model columns to the Triggered Send's attributes, including email addresses and custom attributes. Hightouch matches rows from your model to Marketing Cloud contacts by **Subscriber Key**.

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

> [!NOTE]
>
> For Hightouch platform error codes related to SFMC, see [Error codes:
> SFMC](https://docs.hightouch.com/developer-tools/error-codes.md#salesforce-marketing-cloud-sfmc).

### Validate your setup

After you configure your sync, run a test to confirm data flows correctly:

1. Start with a small test audience or a single record.
2. Trigger a manual sync from the [Syncs overview](https://app.hightouch.com/syncs?from=docs) page.
3. After the sync completes, verify the data in SFMC:
   * For Data Extension syncs, open the target Data Extension in **Audience Builder → Contact Builder → Data Extensions** and confirm your records appear with the expected field values.
   * For Contact syncs, search for the test contact in **Contact Builder** and verify attributes.
   * For Triggered Send syncs, check the **Tracking** tab of the Triggered Send to confirm delivery.
4. If the sync shows errors, check the sync run log in Hightouch for specific API error messages.

### Choosing a sync method for Data Extensions

When syncing [Data Extensions](#data-extensions), three sync methods are available. Choose based on your volume and debugging needs:

* **Upsert via SOAP API** — Best for smaller datasets or when you need detailed per-row error messages. The SOAP API is limited to approximately 2,000 requests per minute, so large syncs can be slow.
* **Upsert via [file uploads](#automatic-file-import-via-file-uploads)** — Best for large datasets (over 1 million records). Hightouch uploads records via SFTP, which is significantly faster than SOAP. Error messages are less granular.
* **[Mirror](#data-extensions)** — Best when you need to fully replace the Data Extension contents each sync, such as heavy deletion use cases. Mirror always uses file uploads.

If you're unsure, start with upsert via file uploads for production syncs and switch to SOAP temporarily when debugging row-level errors.

### DateTime timezone conversions

SFMC converts all incoming datetime values to UTC and displays them in the account's configured timezone. This can cause apparent date shifts — for example, a timestamp of `2026-06-02 22:00:00 America/Los_Angeles` is stored as `2026-06-03 05:00:00 UTC`, which may display as June 3 instead of June 2.

To avoid this:

* Add a transformed column in your data source that includes explicit timezone information (for example, an ISO 8601 string with a timezone offset like `2026-06-02T22:00:00-07:00`).
* Alternatively, use a timezone conversion function in your model query. For example, in Snowflake: `CONVERT_TIMEZONE('America/Los_Angeles', 'UTC', your_timestamp_column)`.

## Common errors

| Error message | Description |
| :- | :- |
| `Failed to create Data Extension` | Incomplete sync configuration with missing field names or types. [More detail.](#failed-to-create-data-extension) |
| `Instance validation error: ... is not a valid value for DataExtensionFieldType` | Data Extension name conflicts with an existing one. [More detail.](#instance-validation-error-data-type-value-is-not-a-valid-value-for-dataextensionfieldtype) |
| `The event data contains duplicate values for an existing primary key` | Duplicate values in the primary/subscriber key column. [More detail.](#the-event-data-contains-duplicate-values-for-an-existing-primary-key) |
| `The Custom Object field selected must have a type of Number or Long Number` | Subscriber ID field mapped to a non-numeric type. [More detail.](#the-custom-object-field-selected-must-have-a-type-of-number-or-long-number) |
| `Adding a new Data Extension definition is not allowed when doing an update-only operation` | Data Extension was deleted or name collides with an existing one. [More detail.](#adding-a-new-data-extension-definition-is-not-allowed-when-doing-an-update-only-operation) |
| `FileNotFound: Soap Error (import instance could not be validated)` | SFMC can't access the uploaded file due to FTP credential or directory issues. [More detail.](#filenotfound-soap-error-import-instance-could-not-be-validated) |
| `Mirror sync shows failure but most records are present in SFMC` | A few rows failed validation, marking the entire sync run as failed. [More detail.](#mirror-sync-shows-failure-but-most-records-are-present-in-sfmc) |
| `invalid_client` authentication error | The installed package's client secret expired or is invalid. [More detail.](#invalid_client-authentication-error) |
| `scope_mismatch` when reading campaigns or templates | The installed package doesn't grant a scope Hightouch requested. [More detail.](#scope_mismatch-when-reading-campaigns-or-templates) |

### Failed to create Data Extension

```
Failed to create Data Extension
```

**Cause:** The sync configuration is incomplete — field names or field types are missing.

**Solution:** Open your sync configuration and ensure you've entered the field names and selected the field types when [creating new fields](#field-creation).

### Instance validation error: 'DATA TYPE VALUE' is not a valid value for DataExtensionFieldType

```
Server was unable to read request. ---> There is an error in the XML document. ... 'DATA TYPE VALUE' is not a valid value for DataExtensionFieldType
```

**Cause:** The sync is configured to create a new Data Extension with the same name as one that already exists in SFMC.

**Solution:** Change the name of the Data Extension in your sync configuration to a unique name, and select field types for each mapped column.

### The event data contains duplicate values for an existing primary key

```
400 - {"message":"The event data contains duplicate value for an existing primary key. Please correct the event data and try again.","errorcode":30000,"documentation":""}
```

**Cause:** The column selected as the primary or subscriber key contains duplicate values.

**Solution:** Ensure the key column doesn't contain duplicates. Update your [model definition](https://docs.hightouch.com/models/creating-models.md) to deduplicate if needed. See [syncing Data Extensions](#data-extensions) for more on key configuration.

### The Custom Object field selected must have a type of Number or Long Number

```
The Custom Object field selected must have a type of Number or Long Number
```

**Cause:** You chose to make the Data Extension sendable and set the subscriber relationship using the Subscriber ID, but the mapped field isn't a numeric type.

**Solution:** Either map a numeric field to the Subscriber ID, or map the field to the Subscriber Key instead. See SFMC's [Subscriber data view documentation](https://help.salesforce.com/s/articleView?id=sf.mc_as_data_view_subscribers.htm\&type=5) for field type requirements.

### Adding a new Data Extension definition is not allowed when doing an update-only operation

```
Could not create data extension fields: Error: Soap Error Key: ... Adding a new Data Extension definition is not allowed when doing an update-only operation
```

**Cause:** Either the Data Extension set in the sync configuration has been deleted from SFMC, or the sync is set to [automatically create a new Data Extension](#automatic-data-extension-creation) with a name that matches an existing Data Extension.

**Solution:** Ensure your sync sends data to an existing Data Extension. If the sync is creating a new Data Extension, use a unique name that doesn't already exist in your SFMC environment.

### FileNotFound: Soap Error (import instance could not be validated)

```
FileNotFound: Soap Error Key: ... import instance could not be validated
```

**Cause:** SFMC can't access or find the file uploaded by Hightouch. This typically points to FTP credential or directory configuration issues.

**Solution:**

1. Verify the FTP credentials in your destination configuration are correct. Test them by connecting to the SFTP outside of Hightouch.
2. Ensure the FTP user has access to the correct file location. If you have multiple business units, create the FTP user in the parent business unit or the same business unit as the target Data Extension.
3. Check the FTP user's home directory in SFMC. If it's set to something other than `/`, files may be written to a nested directory instead of the `Import/` directory. Set the home directory to `/` (the default).
4. If you're using a blob-storage file location (AWS S3 or GCS), ensure the configured role has read permissions.

### Mirror sync shows failure but most records are present in SFMC

```
Sync run failed (Mirror mode)
```

**Cause:** A small number of records failed validation on the SFMC side — for example, due to data type mismatches or missing required fields. Any rejected rows cause the entire sync run to be marked as failed.

**Solution:** Check the **Rejected rows** tab in the sync run details to identify the specific records that failed. Fix the underlying data issues in your model, then rerun the sync.

### invalid\_client authentication error

```
401 - {"error":"invalid_client","error_description":"Invalid client ID or client secret"}
```

**Cause:** The installed package's client secret expired or is invalid. SFMC client secrets expire 180 days after they're generated, and all secrets created before this policy took effect expire on September 30, 2026.

**Solution:** Rotate the client secret and update it in Hightouch by following the steps in [Client secret rotation](#client-secret-rotation).

### scope\_mismatch when reading campaigns or templates

```text theme={null}
400 - {"error":"scope_mismatch","error_description":"Your integration doesn't include this scope. Update the scopes of your integration in Marketing Cloud Installed Packages."}
```

**Cause:** Hightouch requested an OAuth scope that the installed package doesn't grant. This usually happens when you connect SFMC in Context Hub with a package that was set up only for syncing.

**Solution:** In SFMC, go to **Setup > Apps > Installed Packages** and grant the missing permissions to the package's API integration. See Context Hub connections for the full list. If the destination's **Custom scopes** field lists scopes, add the new ones there too.