Salesforce Marketing Cloud Destination

Salesforce Marketing Cloud (SFMC) provides digital marketing automation and analytics software and services. Marketers can use this software to create sophisticated multi-channel campaigns using the SFMC Journey Builder. This is a campaign planning tool that helps you design and automate campaigns that guide customers through their journey with your brand, such as Weekly Product Summary Emails that you can enable with Segment.

SFMC quick info

Segment and SFMC

Segment sends data to SFMC using Data Extensions, or using API Events.

• Data Extensions are tables that contain your data. When this data arrives in SFMC, you can use it to create targeted marketing campaigns using push notifications and emails. You can view and query Data Extensions using the Journey Builder in SFMC. During the set up process, you will create a Data Extensions for Identify calls, and one for each unique Track call.

• API Events can trigger an email or push notification campaign immediately when they receive data from Segment.

SFMC prerequisites

Before you start working with SFMC, work through the following sections to confirm that the destination will work as you expect, and set up any authentication requirements.

Confirm that Salesforce Marketing Cloud supports your source type and connection mode

Before you start, make sure Salesforce Marketing Cloud supports the source type and connection mode you’ve chosen to implement. You can learn more about connection modes here.

Grant Segment API access to Salesforce Marketing Cloud

1. Log in to your Salesforce Marketing Cloud account and go to the Setup settings.
2. Under Platform Tools, expand Apps and select Installed Packages.
3. Click New to create a new package. We recommend giving it a name like “Segment”.
4. Click Add Component and select API Integration.
5. Select the Server-to-Server Integration Type.
6. Enable the following permissions. If you don’t add these permissions, you’ll see an Insufficient Privileges error from SFMC.
   • Email: Read, Write
   • Web: Read, Write
   • Automations: Read, Write, Execute
   • Journeys: Read
   • List And Subscribers: Read, Write
   • Data Extensions: Read, Write
   • Tracking Events: Read
   • Webhooks: Read, Write
7. Click Save.

Once you save the API integration and add permissions, SFMC shows a Summary page with a Components section. This section lists your Client ID and Client Secret settings.

Find your SFMC subdomain

Segment uses your unique Salesforce subdomain to make API calls to SFMC. Your subdomain is a 28-character string that starts with the letters “mc” in any of your base URIs. For example, in the base URI mc563885gzs27c5t9-63k636ttgm.rest.marketingcloudapis.com, the subdomain is mc563885gzs27c5t9-63k636ttgm. When you find your subdomain, record it as you will use it in the SFMC Destination Settings in the Segment App.

Optional: Set up SFMC batching

SFMC has strict rate limits, usually 20 requests per second. If your organization sends a very high volume of data or has audiences with many people in them, Segment allows you to send data to SFMC in batches. This can help you reduce your SFMC API quota, reduce the number of rate-limiting errors you see, and help speed up transfers of large volumes of data.

To use the SFMC Batch feature:

1. Make sure you don’t need to use API Events or create contacts from Identify calls. If you have the SFMC Batch Integration enabled, you cannot use these two features at all.
2. Enable the SFMC Data Extensions Async API on your account. SFMC requires that each customer specifically request access to the Salesforce API that allows Segment to send batched data to SFMC. Contact your account representative to enable the asynchronous REST API endpoints. This step is required. If you do not enable these endpoints, your data will be dropped. This setting is configured by Salesforce per account, so if the account can already access these endpoints, go to the next step.
3. Contact Segment to enable batching for each SFMC destination. Once you confirm that you have access to the async API endpoints, contact your Segment CSM or Segment Product Support to request that batching be enabled on your Segment account. You must do this step for each instance of the SFMC destination that you create in your Segment workspace. Provide the Support team with a link to the SFMC destination you want to enable this functionality on.
4. Once you complete these enablement steps, follow the standard set up instructions for the SFMC destination below.

If possible, you should enable batching for your SFMC destination before you send it any data. If you enable batching for an existing SFMC destination that has already received Segment data, you must work with Segment Product Support to migrate that data.

Set up to send Identify calls to SFMC

To use the Journey Builder to send campaigns to your users, you need to have data about those users in SFMC. The most common way to send data to SFMC is to send Segment Identify calls to an SFMC Data Extension which you specify. When you call identify, Segment creates a Salesforce Marketing Cloud Contact, and upserts (updates) the user’s traits in the Data Extension.

Create a Data Extension in SFMC to store Identify calls

You must create a Data Extension in SFMC to store the Identify calls coming from Segment. For each trait you want to send to SFMC, you must manually create an attribute on the Data Extension in SFMC. When you create a Data Extension in SFMC, you can set up as many (or as few) attributes as you need.

• SFMC ignores keys that don’t exist in the target data extension, so you must create attributes before you send the data to SFMC. Attributes created in the Data Extension cannot be applied retroactively. If you send a trait "nonexistent": "xyz" with your data, but there’s no matching nonexistent column in SFMC’s table, that trait is ignored.
• You do not need to create attributes for all of the traits in an Identify call. If you don’t need a specific trait in SFMC, don’t create an attribute for it, and Segment ignores the trait when it sends data to SFMC.
• All attributes you create in the Data Extension must be in Title Case, regardless of the casing used in your Segment Identify calls. When Segment sends Identify calls to SFMC it first transforms the data to use Title Case, but you still need to set the attributes up in SFMC in the correct format.
• Set up a Primary Key in the Identify Data Extension called **Contact Key**. Segment uses this to link users to SFMC’s built-in Contact Key property. This field is populated with userId by default in Identify calls. If no userId exists, Segment uses the email instead.
• If you want to use this data to send emails or push notifications, check the Is Sendable box. (If you need to do this later, the box will be called “Used for Sending”.)
• If you will be using this data to send emails, set up any Email attributes so they are of the “EmailAddress” type.

Before you leave this screen, copy the External Key for the Data Extension. You’ll need it to set up the destination in Segment.

The example below shows a Data Extension for Identify calls that stores Email, First Name, and Last Name traits. Note the external key in the left column.

Configure the Salesforce Marketing Cloud Destination in Segment

1. Add the Salesforce Marketing Cloud Destination to your Segment Workspace.
2. In the Destination Settings, locate the Identify Data Extension External Key setting. Enter the External Key you copied for the Data Extension that you set up in SFMC.

Data Formatting Requirements

SFMC is very strict about the format of your data, and rejects calls if they don’t fit an expected format.

To keep your data format consistent, predictable, and readable in SFMC, Segment converts all of your property keys to Title Case before sending them to SFMC. For example, the following example data:

{
  "firstName": "Amanda",
  "lastName": "Smith",
  "email": "amanda@example.com",
  "createdAt": "2020-05-30T13:30:00+00:00"
}

or

{
  "first_name": "Amanda",
  "last_name": "Smith",
  "email": "amanda@example.com",
  "created_at": "2020-05-30T13:30:00+00:00"
}

are converted to:

{
  "First Name": "Amanda",
  "Last Name": "Smith",
  "Email": "amanda@example.com",
  "Created At": "2020-05-30T13:30:00+00:00"
}

There are a few more things you should to know about sending data to SFMC:

• You must include a userId or email trait in every Identify call. Segment does not forward Identify calls to SFMC if both are missing.
  • If userId is present in the Identify call, Segment sends it to SFMC as the Contact Key
  • If no userId is present, Segment sends the email in the Identify to SFMC as the Contact Key
  • SFMC does not allow colon characters (“:”) in the Contact Key field, so you must remove those characters from any userId fields.
• SFMC doesn’t handle nested objects gracefully, so Segment excludes any nested properties from the data it sends. To send nested context fields, see the section on Using Context Properties below.
• SFMC accepts ISO-8601-formatted dates, and rejects any calls that include dates not in that format. Make sure you send all dates in ISO format.

Set up to send Track calls to SFMC

You can use Segment Track calls to send rich data about what your users are doing to a Data Extension in SFMC, which you can then use to build Journeys. When you send Track calls to SFMC, Segment fires an event using SFMC’s eventing API.

Create a Data Extension in SFMC for each Track event

You must create a Data Extension in SFMC to store the Track calls coming from Segment. For each property you want to send to SFMC, you must manually create an attribute on the Data Extension in SFMC. When you create a Data Extension in SFMC, you can set up as many (or as few) attributes as you need.

For example, you could make the following track call using Segment:

analytics.track("User Registered", {
    "plan": "Free Trial"
})

To make this data available in SFMC, you would create a new Data Extension with the name User Registered, and with an attribute of Plan.

• All attributes you create in the Data Extension must be in Title Case, regardless of the casing used in your Segment Track calls. When Segment sends Track calls to SFMC it first transforms the data to use Title Case, but you still need to set the attributes up in SFMC in the correct format.
• Create an attribute called Contact Key in the Track Data Extension. Segment sends the userId to this attribute if one is available in the Track call.
• SFMC ignores keys that don’t exist in the target data extension, so you must create attributes before you send the data to SFMC. Attributes created in the Data Extension cannot be applied retroactively. If you send a property "nonexistent": "xyz" with your data, but there’s no matching nonexistent column in SFMC’s table, that property is ignored.

When you finish setting up the Data Extension, copy the External Key. You’ll use this to configure the SFMC destination in Segment.

The example below shows a Data Extension for User Registered Track calls that stores the userId, timestamp, and plan properties:

Configure the SFMC Destination in Segment

You must add a Conversion Event in the SFMC Destination settings in the Segment App for each Track event you send to SFMC.

Just as you did for the Identify Data Extension, copy and paste the External ID of the Track Data Extension into the Conversion Events setting.

1. Add the Salesforce Marketing Cloud Destination to your Segment Workspace if you haven’t already.
2. In the Destination Settings, locate the “Conversion events” setting. Enter the External Key you copied for the Track Data Extension that you set up in SFMC.

Configuring Primary Keys for each conversion event

Segment uses the Primary Key you define in the Conversion Events setting to deduplicate records in the Data Extension.

For example, if you use Contact Key as your Primary Key, the userId from the Segment Track call becomes the Primary Key for that Data Extension. The Data Extension maintains one row per userId, and updates the attributes in that row with the latest values coming from Segment.

If you send two events to the Data Extension and they have the same Primary Key value, the events deduplicate and the Data Extension contains the most recent attribute values that SFMC received. This means you should be thoughtful about which property to use as a Primary Key.

For example, you might use Contact Key as the Primary Key to pass the Segment userId for each event into SFMC. However, if you set Contact Key as the Primary Key for the Button Pressed event, the Data Extension will only maintain one record per user in the Button Pressed Data Extension, even though each user will probably click more than one button.

You don’t have to use Contact Key if there are other properties that make more sense to use as the Primary Key for that Track event. For example, you might want to use ProductId as the Primary Key if you want Order Completed Track events in the Data Extension to create a table of your products, with one row per product.

If you don’t want to deduplicate rows, you can check the UUID Primary Key to create a table of every single Track event that you pass into the Data Extension. When you check this box it overrides any setting in the Primary Key Field, and Segment passes a Primary Key of Uuid with a value that is the messageId. If you check this box, make sure you create an attribute for Uuid in the Data Extension before sending any data.

If we return to the example of one user clicking multiple buttons, if you check the UUID Primary Key box then every time the user clicks a button, it creates a new record in the Button Clicked Data Extension.

Using multiple Primary Keys

You can use more than one Primary Key if needed. To add more than one Primary Key, enter them in the Primary Key Field separated by a comma. For example, if for the Primary Keys Contact Key and Product Id, you enter Contact Key,Product Id. The order of the keys does not change the deduplication behavior.

You might use more than one primary key if, for example, you want to track if a user clicks the Start Button and the Stop Button, but you don’t care how many time the users clicked them. In this case, you could use Contact Key and Button Title as Primary Keys. Then, SFMC only deduplicates if both Contact Key (the user) and Button Title are the same. This means you would record that individual users clicked the Start Button and the Stop Button, but not how many times they clicked them.

Using context properties from Identify or Track calls

The Segment SDKs and libraries automatically collect many context properties, and you can pass these properties into SFMC as Data Extension attributes.

To use context properties, you must create attributes in the Data Extensions that use specific naming conventions. The table below lists the Segment context properties available for SFMC, and the Data Extension attribute names they map to.

Using Personas with SFMC

You can send audiences and computed traits created in Segment Personas to SFMC to run more effective marketing campaigns.

In order to do this, you must have access to Personas. To learn more, contact Segment for a demo.

Set up Personas with SFMC in Segment

1. In your Personas space, add the SFMC destination to a computed trait or audience.
2. You can either sync to an existing Data Extension or you can make the sync create a new Data Extension in SFMC.
   • To Create a new Data Extension leave the Data Extension External Key blank. This creates a new Data Extension in the default location configured for your SFMC instance, with all the required columns.
   • To Sync to an existing Data Extension: enter the Data Extension External Key for the existing Data Extension. When your audience syncs to it, Segment adds a new column which stores the computed trait or audience membership.

If you sync to an existing Data Extension, there are additional requirements:

• The table cannot have an existing Primary Key, unless it is the Contact Key field, and the field type is Text.
• All fields in the Data Extension must be nullable (meaning optional, or not required), except the Contact Key field.
• Any fields that you will send with Segment, and which already exist in the Data Extension must be of the correct data type. If they do not exist, Segment creates them for you. The standard identifiers Segment sends come from the Context object, and appear in the image below.

Syncing Personas Audiences to SFMC

When you add an audience to SFMC, the first sync contains all the users in that audience. A user is added as a new row to the Data Extension the first time they enter an audience. For example, let’s say you have an “Active Users” audience. When you send this audience to SFMC, all the users in the audience are added to a Data Extension, with a column that indicates their audience membership with true. To work correctly, the Personas audience name should be Title Cased in the Data Extension column. Segment automatically creates the column name in Title Case. Do not change the column casing.

If a user leaves that audience, the value is automatically updated to false, but the user is not removed from the Extension. This allows you to see all users who have ever been in the audience, and then optionally create a filtered Data Extension if you want a subset. See the SFMC documentation for more details:

• Create a Filtered Data Extension in Marketing Cloud
• Automatically refresh a Filtered Data Extension

Syncing Personas Computed Traits to SFMC

When you send a computed trait to SFMC, Segment creates a new column named after the computed trait, and which contains the computed trait calculated by Personas value for each user.

Troubleshooting and Tips

Connecting a Segment Workspace to an existing SFMC instance does not work as expected

Currently, the state of your SFMC instance changes how the integration with Segment works. If your SFMC instance is new and empty, then setting up SFMC with Segment works as expected. If your SFMC instance already has Contacts in it, then the implementation with Segment is more complex. We recommend that you use a brand new SFMC instance where possible. Please reach out to friends@segment.com if this causes you problems.

If your SFMC instance already contains data, then when Segment sends Identify calls to SFMC it is not able to dedupe against existing Contact data. Instead, Segment creates duplicate Contacts, then uses the Contact Key to match the Segment and existing Data Extension data. However, this only works for Contacts that Segment creates, which means that you can’t reliably build Journeys that use these Data Extensions to market to existing Contacts.

Sync failures

• Authentication Errors. Confirm that you set up a subdomain correctly, and that you linked to the correct subdomain in the Segment settings for SFMC. If you did not provide a subdomain, Segment uses a legacy endpoint that might result in authentication errors.
• Data Extension Structure. Confirm that the Data Extension columns that Segment syncs to have not been modified. Specifically, syncs fail if you change the column type.

Referencing an email address or phone number in the Journey Builder

When you send an email or push notification, you need to choose which email address or phone number to send to. The options for selecting an email/phone in the Journey Builder look like this:

If you select Use email attribute from Entry Source you can use an email or phone attribute included in the API Event or Data Extension that triggers the Journey. (Otherwise, you must use an email address attribute or the default phone number attribute on a Contact record.) To use this, you must include an email address and phone number as a property or trait in every single Track/Identify call mapped to SFMC.

Personas data takes too long to sync to SFMC the first time

This issue usually occurs for customers that have very large volumes of customer data (10MM+ users), because multiple audiences and traits attempt to send large quantities of backfill data into SFMC at the same time, and compete for the SFMC rate limit. To help with this, avoid syncing multiple new audiences and new traits at the same time. Instead, create an audience, sync it to SFMC and wait for it to complete. Then, create and sync your next audience or trait.

You can also request a higher rate limit from your SFMC account representative. After you confirm the higher rate limit with your SFMC representative, contact Segment Product Support to adjust the rate limit from the Segment side for you.

Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

API Events

Trigger API Events in SFMC in response to Segment events. The SFMC integration will send API Events to SFMC’s /interaction/v1/events endpoint to fire an entry event to initiate a journey. To learn more about SFMC Journeys see the documentation here.

Account ID (optional)

Your Salesforce Marketing Cloud Account identifier (or MID). For instructions on how to find your MID check out SFMC’s documentation. Use this setting to switch between business units.

Client ID

Your Salesforce Marketing Cloud Client ID. For instructions on how to find your Client ID, check out our documentation.

Client Secret

Your Salesforce Marketing Cloud Client Secret. For instructions on how to find your Client Secret, check out our documentation.

Conversion events

Use these fields to map your Segment event names to Salesforce Marketing Cloud Data Extensions. We’ll only send SMC the conversion events you specify.

Do Not Create or Update Contacts

By default, identify events will create or update contacts in SFMC. If you would like to disable this functionality, set this option to true.

Identify Data Extension External Key

Use this setting if you would like Segment identify events to create or update Data Extensions in SFMC. The External Key of the Salesforce Marketing Cloud Data Extension to which you’d like to send Identify data. You can find this in the SFMC interface by navigating to Data & Analytics > Contact Builder > Data Extensions; the extension’s name will appear in the External Key column.

Subdomain

Your subdomain is represented by a 28-character string starting with the letters “mc” in any of your base URIs. For example, in the base URI mc563885gzs27c5t9-63k636ttgm.rest.marketingcloudapis.com, the subdomain is mc563885gzs27c5t9-63k636ttgm