Salesforce Marketing Cloud

Salesforce Marketing Cloud is a comprehensive digital marketing platform that enables publishers to deliver personalized email campaigns and customer journeys at scale.

Setup

Troubleshooting

Overview

Salesforce Marketing Cloud (SFMC) is a leading marketing automation platform that helps organizations manage customer relationships and deliver targeted email communications. Our integration with Salesforce Marketing Cloud enables you to activate Permutive cohorts directly into SFMC Data Extensions for use in email campaigns and automated customer journeys. This integration is a Destination:

Destination: Permutive can activate your cohorts into SFMC Data Extensions, allowing you to target email campaigns with audience segments built in Permutive.

Use cases include:

Send targeted email campaigns to Permutive cohorts based on user behavior and interests.
Create personalized customer journeys in SFMC using Permutive audience segments.
Retarget users via email based on their on-site activity and cohort membership.
Leverage first-party data from Permutive to enhance email marketing performance.

Environment Compatibility

Environment	Supported	Notes
Web		Requires Subscriber Key to be passed via identity management
iOS		Requires Subscriber Key to be passed via identity management
Android		Requires Subscriber Key to be passed via identity management
CTV		Requires Subscriber Key to be passed via identity management
API Direct		Requires Subscriber Key to be passed via identity management

Prerequisites

SFMC Account Access - You must have access to your Salesforce Marketing Cloud account with permissions to create API integrations and manage Data Extensions.
SFMC Subdomain - You must determine the subdomain specific to your Marketing Cloud instance. This can be found in the SFMC dashboard:
1. Navigate to Administration (under your email address in top-right, where logout is)
2. Click the General Settings box
3. Identify the text after “Portfolio Base URL” or “SOAP WSDL” (just the parts between https:// and the first full stop)
4. Example: https://my-subdomain.soap.marketingcloudapis.com/Service.asmx would be my-subdomain
Business Unit Configuration - For each Business Unit you want to send data to, you must configure API integrations in SFMC. You will need:
- A unique name for each Business Unit (alphanumeric, spaces allowed)
- Client ID (generated when you create the API integration package)
- Client Secret (generated when you create the API integration package)
- An identity type/alias tag that should be synced from Permutive to SFMC
Subscriber Key Type - You must determine whether your SFMC Subscriber Keys are text or numeric values. This configuration is required when setting up the integration in the Permutive dashboard.
User ID Alignment - The IDs being synced to Permutive (via permutive.identify in the SDK or API) must match the Subscriber Keys used in SFMC. The Subscriber Key is the primary identifier SFMC uses for contacts, and it must align with the identity type you configure in Permutive.

Setup

Determine SFMC Subdomain

Before configuring API access, determine your SFMC subdomain. This is required for the integration setup in the Permutive dashboard.

Log in to Salesforce Marketing Cloud
Navigate to “Administration” (under your email address in top-right, where logout is)
Click the “General Settings” box
Locate the “Portfolio Base URL” or “SOAP WSDL” field
Extract the subdomain (the text between https:// and the first .)
- Example: https://my-subdomain.soap.marketingcloudapis.com/Service.asmx → subdomain is my-subdomain

The subdomain is consistent across all Business Units in your Marketing Cloud account.

Configure API Integration for Each Business Unit

For each Business Unit you want to activate cohorts to, you must configure API access in Salesforce Marketing Cloud. Repeat these steps for every Business Unit.

In SFMC, navigate to “Installed Packages” under the “Account” dropdown (top-left)
Click the “New” button in the top right
Enter a name and description (e.g., “Permutive {name-of-business-unit}”)
Click “Add Component” and select “API Integration” (should be automatically selected)
Ensure “Perform server-to-server requests” is checked (should be auto-selected)
Scroll down to “Data” section
Under “Data Extensions”, grant both “Read” and “Write” permissions
In the new “API Integration” box under “Components”, record the following for each Business Unit:
- Client ID - Specific to this Business Unit
- Client Secret - Specific to this Business Unit
- Subdomain - Should match the subdomain you determined in Step 1
Keep these credentials secure and note which Business Unit they correspond to

Each Business Unit requires its own API Integration package with unique Client ID and Client Secret credentials.

If you need to revoke Permutive’s access to a specific Business Unit later, delete the corresponding package in “Installed Packages”.

Enable Integration in Permutive Dashboard

Configure the Salesforce Marketing Cloud integration in the Permutive dashboard with your subdomain and Business Unit credentials.

Navigate to the Permutive dashboard
Go to “Settings” → “Integrations”
Find “Salesforce Marketing Cloud” and click “Add Integration”
Enter your SFMC subdomain (from Step 1)
Select Subscriber Key Type - Choose whether your SFMC Subscriber Keys are “text” or “number”
Configure each Business Unit you want to activate cohorts to:
- Name - Enter a descriptive name for the Business Unit (alphanumeric, spaces allowed)
  - This name is used in the Permutive dashboard for reference
  - It’s also used in the Data Folder name created in SFMC (e.g., Permutive (Sales))
  - Does not need to match the MID in Marketing Cloud
- Client ID - Enter the Client ID from the API Integration (from Step 2)
- Client Secret - Enter the Client Secret from the API Integration (from Step 2)
- Identity Type / Alias Tag - Specify the identity type that should be synced from Permutive to SFMC
  - This must match the identity you pass via permutive.identify in the SDK
  - Example: if you use permutive.identify([{id: "12345", tag: "sfmc", priority: 0}]), enter sfmc here
To add additional Business Units, click the ”+ Business unit” button and repeat the configuration
Click “Save” to complete the integration setup

The Identity Type/Alias Tag must match the Subscriber Key you’re using in Salesforce. This is how Permutive maps users to SFMC contacts.

Configure Cohort Activation

Once the integration is enabled, you can configure individual cohorts for activation to SFMC.

In the Permutive dashboard, navigate to one of your cohorts
Look for the Salesforce Marketing Cloud activation option
Select the Business Unit you want to send the cohort data to
Set the activation to fire “Every Time” a user enters or exits the cohort
Enable the activation

When you enable a cohort activation, Permutive will automatically create a Data Extension in SFMC with the same name as your cohort. The Data Extension will be placed in a Data Folder named Permutive (\{business-unit-name\}).

Verify Setup

In the Salesforce Marketing Cloud dashboard, verify that the integration is working correctly.

Navigate to “Data Extensions” in SFMC
Look for the Data Folder named Permutive (\{business-unit-name\})
Inside the folder, you should see Data Extensions corresponding to your activated cohorts
Each Data Extension should contain:
- subscriber_key: The user ID from Permutive
- timestamp: When the user entered the cohort
As users enter and exit cohorts, rows will be added and removed from the Data Extensions

The Data Extension name will match your Permutive cohort name. The description will contain the cohort code and description (if specified).

For web properties, implement identity management using the Permutive Web SDK to pass SFMC Subscriber Keys to Permutive:

// Identify users with their SFMC Subscriber Key
permutive.identify([
  {
    id: "subscriber-key-12345", // SFMC Subscriber Key
    tag: "sfmc", // Must match the Alias tag configured in dashboard
    priority: 0
  }
]);

You should call permutive.identify() whenever you have the user’s SFMC Subscriber Key available. The Subscriber Key is SFMC’s primary identifier for contacts and must match the key used in your SFMC account.

The Subscriber Key type (text or number) must be configured correctly in the Permutive dashboard to match your SFMC configuration.

For iOS applications, implement identity management using the Permutive iOS SDK to pass SFMC Subscriber Keys to Permutive:

// Identify users with their SFMC Subscriber Key
Permutive.shared.identify(
  identifiers: [
    Identifier(
      id: "subscriber-key-12345", // SFMC Subscriber Key
      tag: "sfmc", // Must match the Alias tag configured in dashboard
      priority: 0
    )
  ]
)

You should call Permutive.shared.identify() whenever you have the user’s SFMC Subscriber Key available.

For Android applications, implement identity management using the Permutive Android SDK to pass SFMC Subscriber Keys to Permutive:

// Identify users with their SFMC Subscriber Key
Permutive.getInstance().identify(
  listOf(
    Identifier(
      id = "subscriber-key-12345", // SFMC Subscriber Key
      tag = "sfmc", // Must match the Alias tag configured in dashboard
      priority = 0
    )
  )
)

You should call Permutive.getInstance().identify() whenever you have the user’s SFMC Subscriber Key available.

For server-side implementations or environments without an SDK, use Permutive’s Identify API directly to pass SFMC Subscriber Keys to Permutive:

curl -XPOST https://api.permutive.com/v2.0/identify \
  -H 'X-API-Key: <PUBLIC_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "<PERMUTIVE_ID>",
    "aliases": [
      {
        "id": "<SFMC_SUBSCRIBER_KEY>",
        "tag": "sfmc",
        "priority": 0
      }
    ]
  }'

The tag value must match the Alias tag configured in the Permutive dashboard for the relevant Business Unit. You can retrieve your Public API Key from the Permutive dashboard.

Data Types

When you activate a cohort for SFMC, Permutive creates a Data Extension with the following schema:

Data Extension Structure

Each Data Extension created by Permutive contains user identifiers and membership timestamps for a specific cohort.Naming Convention:

Data Extension Name: Same as your Permutive cohort name (e.g., “Travel Enthusiasts”)
Data Extension Description: Cohort code followed by cohort description (e.g., “12345 - Users interested in travel content”)
Data Folder: All Data Extensions for a Business Unit are organized in a folder named Permutive ({business-unit-name}) (e.g., Permutive (Sales))
External Key: Each Data Extension is assigned a UUID as its External Key, which Permutive uses to identify it

Fields:

Text/Number

required

The user identifier synced to Permutive that maps to SFMC’s Subscriber Key. This is the Alias Tag/Identity Type you configured in the integration setup.

Field type matches the Subscriber Key Type configured in Permutive (text or number)
Configured as the Subscriber Key attribute in SFMC to make the Data Extension sendable
Must match the IDs you pass via permutive.identify in the SDK or API
Primary Key of the Data Extension

Date

The timestamp when the user entered the cohort in Permutive.

Stored without timezone information in SFMC
Used to track when users became members of the cohort

Behavior:

When a user enters the cohort in Permutive, a row is added to the Data Extension with their subscriber_key and entry timestamp
When a user exits the cohort in Permutive, the corresponding row is removed from the Data Extension
Data Extensions are configured as both sendable and testable for use in email campaigns and automated journeys
Segment entries and exits are synced in near real-time (typically within seconds)

Identity Mapping: Alias Tag and Subscriber Key

Understanding the relationship between Permutive’s Alias Tag and SFMC’s Subscriber Key is crucial for successful cohort activation.What is a Subscriber Key?The Subscriber Key is SFMC’s primary identifier for contacts. It’s the unique ID that SFMC uses to identify and target individual users across all email campaigns and customer journeys.What is an Alias Tag?In Permutive, an Alias Tag is the name of an identity type. It’s how you label different types of identifiers when you call permutive.identify. For the SFMC integration, you configure an Alias Tag (e.g., “sfmc”) that represents your SFMC Subscriber Keys.How They Work Together:

You configure the Alias Tag in the Permutive dashboard when setting up the SFMC integration (e.g., “sfmc”)

You identify users in Permutive with their SFMC Subscriber Key using this Alias Tag:

permutive.identify([{
  id: "subscriber-12345",  // The actual SFMC Subscriber Key
  tag: "sfmc",  // The Alias Tag configured in dashboard
  priority: 0
}]);

When a user enters a cohort, Permutive looks up their identifier for the configured Alias Tag
Permutive sends this identifier to SFMC as the subscriber_key in the Data Extension
SFMC can now use this Data Extension to target the user in email campaigns

Important Notes:

The Alias Tag is just a label in Permutive - the actual ID values must be valid SFMC Subscriber Keys
The Subscriber Key type (text or number) must be configured correctly in Permutive to match your SFMC setup
Users must be identified with the Alias Tag before entering a cohort for activation to work
Different Business Units can use different Alias Tags if they use different identifier schemes

Troubleshooting

Dashboard timeout (500 error) during integration setup

If you see a 500 error after approximately 10 seconds when setting up the integration, this is likely due to slow SFMC API response times. The integration should still complete successfully.Solution:

Refresh your browser (hard refresh recommended)
Navigate to Settings → Integrations
Check if Salesforce Marketing Cloud appears in your list of active integrations
If the integration appears, setup was successful despite the timeout
If it doesn’t appear, try the setup process again

Unable to enable integration - Permission errors

If you receive permission errors when trying to enable the integration, check your API integration configuration in SFMC.Solution:

Verify that you’ve granted “Read” and “Write” permissions for Data Extensions in your SFMC API Integration package
Ensure you’re using the correct Client ID and Client Secret for each Business Unit
Confirm that the API Integration is set to “Perform server-to-server requests”
Check that the subdomain is correct

Data Extension not being created when activating cohort

If a Data Extension is not created when you activate a cohort, there may be a configuration issue.Solution:

Verify that the cohort activation is set to fire “Every Time” (this is the only valid option for SFMC)
Check that you’ve selected a Business Unit for the activation
Ensure there are users in the cohort who have been identified with your SFMC identifier type
Look for any error messages in the Permutive dashboard when enabling the activation

Cannot remove or rename Business Unit in dashboard

Once a Business Unit is added to the integration configuration, it cannot be removed or renamed through the dashboard. This is a limitation of the integration design.Solution:

Business Units cannot be removed after being added to the integration configuration
The name of an existing Business Unit cannot be changed after creation
You can edit Client ID, Client Secret, and Alias Tag for existing Business Units, but not the name
If you need to remove a Business Unit entirely, contact Permutive Support for assistance
To revoke Permutive’s access to a specific Business Unit without removing it from Permutive, delete the API Integration package in SFMC’s “Installed Packages” section

Subscriber Key type mismatch

If you configured the wrong Subscriber Key type (text vs. number) in the Permutive dashboard, cohort activations may not work correctly.Solution:

Verify the Subscriber Key type in your SFMC account (check if keys are numeric or text-based)
The Subscriber Key type configured in Permutive must match your SFMC configuration
If you selected the wrong type, contact Permutive Support to update the configuration
Check that the IDs you’re passing via permutive.identify match the expected format (text or number)

Wrong Business Unit selected for cohort activation

If you accidentally activated a cohort to the wrong Business Unit, you can change it.Solution:

In the Permutive dashboard, navigate to the cohort’s activation settings
Select a different Business Unit from the dropdown
The Data Extension will be created in the newly selected Business Unit
The old Data Extension in the previous Business Unit will remain but will no longer receive updates
To clean up, manually delete the old Data Extension in SFMC if desired

Users not appearing in SFMC Data Extensions

If users in your Permutive cohorts are not appearing in SFMC Data Extensions, there may be an ID mismatch.Solution:

Verify that the IDs being sent to Permutive via permutive.identify match the Subscriber Keys in SFMC
Check that you’ve specified the correct identifier type in the integration configuration
Ensure users have been identified in Permutive using the identifier type you configured
Confirm that the Data Extension’s subscriber_key column is set as the Subscriber Key attribute in SFMC

Data Extension moved or renamed - activation stopped working

If you’ve moved or renamed a Data Extension created by Permutive, activations should continue to work.Solution:

Moving Data Extensions to different folders is supported - activations will continue to sync
Renaming Data Extensions is supported - activations use the External Key (UUID) to identify the Data Extension, not the name
Do NOT change the External Key of the Data Extension, as this is used by Permutive to identify the correct Data Extension
New activations will still be created in the original Permutive Data Folder

Timestamps displaying with unexpected timezone

Timestamps in SFMC Data Extensions may not display in the timezone you expect.Solution:

Timestamps are stored without timezone information in SFMC
The displayed timezone may differ from UTC depending on SFMC’s internal handling
This is a known limitation and does not affect the functionality of the integration
Consider the timestamp as a relative indicator of when users entered cohorts rather than an absolute time

Can reactions be set up automatically for new segments?

No, SFMC cohort activations cannot be automatically enabled when you create a new segment in Permutive.Solution:

You must manually enable the SFMC activation for each cohort you want to sync
Navigate to the cohort in the Permutive dashboard
Toggle the SFMC activation to “On”
Select the Business Unit and configure the activation settings

Changelog

For detailed changelog information, visit our Changelog.

Integrations

Identity

Contextual

Advertising

Marketing

Data Collaboration

Video

Social Media

Survey

Salesforce Marketing Cloud