(API) Salesforce Marketing Cloud connection

Overview

Salesforce Marketing Cloud (formerly known as ExactTarget) is a digital marketing suite that allows you to build and customize journeys for visitors and customers to personalize their experience.

IMPORTANT

Note the difference between this connection and the other Salesforce Marketing Cloud connection that exists within the Email marketing catalog section. The other Salesforce Marketing Cloud connection allows you to export files to a specified storage location, whereas this is an API-based streaming connection.

This Adobe Experience Platform destination leverages the Salesforce Marketing Cloud update contacts API, which allows you to add contacts / update contact data for your business needs after activating them within a new Salesforce Marketing Cloud segment.

Salesforce Marketing Cloud uses OAuth 2 with Client Credentials as the authentication mechanism to communicate with the Salesforce Marketing Cloud API. Instructions to authenticate to your Salesforce Marketing Cloud instance are further below, in the Authenticate to destination section.

Use cases

To help you better understand how and when you should use the Salesforce Marketing Cloud destination, here is a sample use case that Adobe Experience Platform customers can solve by using this destination.

Send emails to contacts for marketing campaigns

The sales department of a home rental platform wants to broadcast a marketing email to a targeted customer audience. The platform’s marketing team can add new contacts / update existing contacts (and their email addresses) through Adobe Experience Platform, build segments from their own offline data, and send these segments to Salesforce Marketing Cloud, which can then be used to send the marketing campaign email.

Prerequisites

Prerequisites in Experience Platform

Before activating data to the Salesforce Marketing Cloud destination, you must have a schema, a dataset, and segments created in Experience Platform.

Prerequisites in Salesforce Marketing Cloud

Note the following prerequisites in order to export data from Platform to your Salesforce Marketing Cloud account:

You need to have a Salesforce Marketing Cloud account

Reach out to your Salesforce Account Executive to subscribe to the Salesforce Marketing Cloud Account Engagement product if you do not have it already.

Create custom field within Salesforce Marketing Cloud

You must create a custom attribute of the type Text Area Long, which Experience Platform will use to update the segment status within Salesforce Marketing Cloud. In the workflow to activate segments to the destination, in the Segment schedule step, you will use the custom attribute as Mapping ID for each segment you activate.

Refer to the Salesforce Marketing Cloud documentation to create custom fields if you need additional guidance.

IMPORTANT

Ensure you create the custom attribute under the Email Demographics attribute-set within your Salesforce Marketing Cloud account.

Refer to the Adobe Experience Platform documentation for Segment Membership Details schema field group if you need guidance on segment statuses.

Gather Salesforce credentials

Note down the items below before you authenticate to the Salesforce Marketing Cloud destination.

Credential Description Example
  • Salesforce Marketing Cloud prefix
See Salesforce Marketing Cloud domain prefix for additional guidance.
  • If your domain is as below, you need the highlighted value.
    mcq4jrssqdlyc4lph19nnqgzzs84.login.exacttarget.com
  • Client ID
  • Client Secret
Refer to the Salesforce Marketing Cloud documentation if you need additional guidance.
  • r23kxxxxxxxx0z05xxxxxx
  • ipxxxxxxxxxxT4xxxxxxxxxx

Limits in Salesforce Marketing Cloud

  • Salesforce imposes certain rate limits.
    • Refer to the Salesforce Marketing Cloud documentation to address any probable limits that you might encounter and reduce errors during execution.
    • Refer to the Salesforce Marketing Cloud Engagement Pricing page to Download the Full Edition Comparison Chart as a pdf which details the limits imposed by your plan.
    • The API overview page details additional limits.
    • Refer here for a page which collates these details.
  • The count of custom fields allowed per object varies according to your Salesforce Edition.
    • Refer to the Salesforce documentation for additional guidance.
    • If you have reached the limit defined for custom fields allowed per object within Salesforce Marketing Cloud you will need to
      • Remove older custom fields before adding new custom fields in Salesforce Marketing Cloud.
      • Update or remove any destinations in Platform which use these older custom field names as the value provided for Mapping ID during the segment scheduling step.

Supported identities

Salesforce Marketing Cloud supports the activation of identities described in the table below. Learn more about identities.

Target Identity Description Considerations
contactKey Salesforce Marketing Cloud Contact Key. Refer to the Salesforce Marketing Cloud documentation if you need additional guidance. Mandatory

Export type and frequency

Refer to the table below for information about the destination export type and frequency.

Item Type Notes
Export type Profile-based
  • You are exporting all members of a segment, together with the desired schema fields (for example: email address, phone number, last name), according to your field mapping.
  • Each segment status in Salesforce Marketing Cloud gets updated with the corresponding segment status from Platform, based on the Mapping ID value provided during the segment scheduling step.
Export frequency Streaming Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on segment evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations.

Connect to the destination

IMPORTANT

To connect to the destination, you need the Manage Destinations access control permission. Read the access control overview or contact your product administrator to obtain the required permissions.

To connect to this destination, follow the steps described in the destination configuration tutorial. In the configure destination workflow, fill in the fields listed in the two sections below.

Within Destinations > Catalog, search for (API) Salesforce Marketing Cloud. Alternatively you can locate it under the Email marketing category.

Authenticate to destination

To authenticate to the destination, fill in the required fields and select Connect to destination.
Platform UI screenshot showing how to authenticate to Salesforce Marketing Cloud.

  • Subdomain: Your Salesforce Marketing Cloud domain prefix. For example if your domain is mcq4jrssqdlyc4lph19nnqgzzs84.login.exacttarget.com, you need the highlighted value.
  • Client ID: Your Salesforce Marketing Cloud Client ID.
  • Client Secret: Your Salesforce Marketing Cloud Client Secret.

If the details provided are valid, the UI displays a Connected status with a green check mark, you can then proceed to the next step.

Fill in destination details

To configure details for the destination, fill in the required and optional fields below. An asterisk next to a field in the UI indicates that the field is required.
Platform UI screenshot showing the destination details.

  • Name: A name by which you will recognize this destination in the future.
  • Description: A description that will help you identify this destination in the future.

Enable alerts

You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.

When you are finished providing details for your destination connection, select Next.

Activate segments to this destination

IMPORTANT

To activate data, you need the Manage Destinations, Activate Destinations, View Profiles, and View Segments access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.

Read Activate profiles and segments to streaming segment export destinations for instructions on activating audience segments to this destination.

Mapping considerations and example

To correctly send your audience data from Adobe Experience Platform to the Salesforce Marketing Cloud destination, you need to go through the field mapping step. Mapping consists of creating a link between your Experience Data Model (XDM) schema fields in your Platform account and their corresponding equivalents from the target destination. To correctly map your XDM fields to the Salesforce Marketing Cloud destination fields, follow the steps below.

IMPORTANT

Although your attribute names would be as per your Salesforce Marketing Cloud account, the mappings for both contactKey and personalEmail.address are mandatory.

  1. In the Mapping step, select Add new mapping. You will see a new mapping row on the screen.
    Platform UI screenshot example for Add new mapping.

  2. In the Select source field window, choose the Select attributes category and select contactKey.
    Platform UI screenshot example for Source mapping.

  3. In the Select target field window, select the type of target field that you want to map your source field to.

    • Select identity namespace: select this option to map your source field to an identity namespace from the list.
      Platform UI screenshot showing Target mapping for salesforceContactKey.

    • Add the following mapping between your XDM profile schema and your Salesforce Marketing Cloud instance:

      XDM Profile Schema Salesforce Marketing Cloud Instance Mandatory
      contactKey salesforceContactKey Yes
    • Select custom attributes: select this option to map your source field to a custom attribute that you define in the Attribute name field. Refer to Salesforce Marketing Cloud documentation for a list of supported attributes. Also note that the destination uses the Salesforce Search Attribute-Set Definitions REST API to retrieve attributes defined within Salesforce for your contacts and specific to your account.
      Platform UI screenshot showing Target mapping.

    • For instance, depending on the values you want to update, add the following mapping between your XDM profile schema and your Salesforce Marketing Cloud instance:

      XDM Profile Schema Salesforce Marketing Cloud Instance
      person.name.firstName Email Demographics.First Name
      personalEmail.address Email Addresses.Email Address
    • An example using these mappings is shown below:
      Platform UI screenshot example showing Target mappings.

Schedule segment export and example

When performing the Schedule segment export step, you must manually map Platform segments to the custom attribute in Salesforce.

To do this, select each segment, then enter the corresponding custom attribute from Salesforce in the Mapping ID field.

IMPORTANT

The value used for the Mapping ID should exactly match the name of the custom attribute created within Salesforce under the “Email Demographics” attribute-set.

An example is shown below:
Platform UI screenshot example showing Schedule segment export.

Validate data export

To validate that you have correctly set up the destination, follow the steps below:

  1. Select Destinations > Browse to navigate to the list of destinations.
    Platform UI screenshot showing Browse Destinations.

  2. Select the destination and validate that the status is enabled.
    Platform UI screenshot showing Destinations Dataflow Run.

  3. Switch to the Activation data tab, then select a segment name.
    Platform UI screenshot example showing Destinations Activation Data.

  4. Monitor the segment summary and ensure that the count of profiles corresponds to the count created within the segment.
    Platform UI screenshot example showing Segment.

  5. Log in to the Salesforce Marketing Cloud website. Then navigate to the Audience Builder > Contact Builder > All contacts > Email page and check if the profiles from the segment have been added.
    Salesforce Marketing Cloud UI screenshot showing the Contacts page with profiles used in the segment.

  6. To check if any profiles have been updated, navigate to the Email page and verify if the attribute values for the profile from the segment have been updated. If successful, you can see that each segment status in Salesforce Marketing Cloud was updated with the corresponding segment status from Platform, based on the Mapping ID value provided in the segment scheduling step.
    Salesforce Marketing Cloud UI screenshot showing the selected Contacts Email page with updated segment statuses.

Data usage and governance

All Adobe Experience Platform destinations are compliant with data usage policies when handling your data. For detailed information on how Adobe Experience Platform enforces data governance, see the Data Governance overview.

Errors and troubleshooting

Unknown errors encountered while pushing events to Salesforce Marketing Cloud

When checking a dataflow run, you might encounter the following error message: Unknown errors encountered while pushing events to the destination. Please contact the administrator and try again.

Platform UI screenshot showing error.

To fix this error, verify that the Mapping ID that you provided in Salesforce Marketing Cloud for your Platform segment is valid and exists within Salesforce Marketing Cloud.

Additional resources

On this page