Salesforce Marketing Cloud

Datafly Signal delivers events to Salesforce Marketing Cloud Engagement server-to-server, firing entry events into Journey Builder via the Interaction API. This lets you trigger email and SMS journeys directly from behavioural and conversion signals without relying on a separate batch sync or client-side beacon.

Prerequisites

Before configuring Marketing Cloud in Signal, you need an Installed Package with API credentials and a configured event in Journey Builder.

Step 1: Identify your tenant subdomain

Marketing Cloud assigns every tenant a unique subdomain prefix that appears in every API URL. For example, if your REST URL is https://mc-abc123xyz.rest.marketingcloudapis.com, your subdomain is mc-abc123xyz.

You can find your subdomain in Setup > Apps > Installed Packages — click any package and look at the REST Base URI field.

Step 2: Create an Installed Package

1. In Marketing Cloud, go to Setup > Apps > Installed Packages.
2. Click New and give your package a name (e.g. Datafly Signal).
3. After creation, click Add Component > API Integration.
4. Choose Server-to-Server as the integration type.
5. Grant the following scopes:
   • Journeys: Read, Write, Execute
   • Contacts: Read, Write
   • Data Extensions: Read, Write (only required if you intend to write to data extensions in addition to triggering journeys)
6. Save the component. Marketing Cloud will generate a Client ID and Client Secret — copy both immediately.

Step 3: Identify your Account ID (MID)

If your Marketing Cloud tenant has multiple business units, you’ll need the numeric MID of the business unit you want events delivered to. Find it under Setup > Business Units — the MID column shows a numeric value like 7281234.

Tenants with a single business unit can omit this field.

Step 4: Create an event in Journey Builder

Signal triggers journeys by firing an Engagement Event by key. Create one in Journey Builder:

1. Go to Journey Builder > Events.
2. Click Create Event > API Event.
3. Give it a name and an Event Definition Key — this is the string Signal will reference, e.g. datafly_lead_submitted.
4. Define the schema (the fields the journey expects in the Data payload — email, first_name, etc.).
5. Save the event. You’ll bind it to one or more journeys later.

Configure in Signal

Configuration fields

Management UI setup

1. Go to Integrations > Add Integration > Salesforce Marketing Cloud.
2. Select the Retail preset (or another vertical preset if available).
3. Enter your tenant_subdomain, client_id, client_secret, and event_definition_key. Add account_id if you’re on a multi-business-unit tenant.
4. Set consent categories — defaults to marketing.
5. Click Save.

Management API setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "salesforce_marketing_cloud",
    "name": "Marketing Cloud — Welcome Journey",
    "enabled": true,
    "config": {
      "tenant_subdomain": "mc-abc123xyz",
      "client_id": "abc123clientid",
      "client_secret": "shh-secret-value",
      "event_definition_key": "datafly_lead_submitted"
    },
    "consent_categories": ["marketing"]
  }'

API flow

Signal performs a two-stage call per integration:

Stage 1: Auth

POST https://{tenant_subdomain}.auth.marketingcloudapis.com/v2/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "account_id": "{account_id}"
}

Returns a short-lived access_token (typically 20 minutes). Signal caches the token and refreshes it automatically before expiry.

Stage 2: Send event

POST https://{tenant_subdomain}.rest.marketingcloudapis.com/interaction/v1/events
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "ContactKey": "jane.doe@example.com",
  "EventDefinitionKey": "datafly_lead_submitted",
  "Data": {
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+447700900123",
    "lead_type": "newsletter",
    "lead_value": 0
  }
}

ContactKey is the stable identifier Marketing Cloud uses to find or create a Contact. By default Signal uses the user’s email; if your tenant uses a different ContactKey scheme (e.g. CRM ID), remap ContactKey in the integration’s Field Mappings.

Identity

Event mapping

Retail preset

The EventDefinitionKey sent to Marketing Cloud comes from the integration config (event_definition_key). To trigger different journeys from different Signal events, create one Marketing Cloud integration per journey, each pointing at a different Event Definition Key.

Example: Lead Submitted

Datafly.js call:

datafly.identify("user-123", {
  email: "jane.doe@example.com",
  firstName: "Jane",
  lastName: "Doe",
  phone: "+447700900123"
});
 
datafly.track("Lead Submitted", {
  lead_type: "newsletter",
  value: 0,
  currency: "GBP"
});

Marketing Cloud payload sent by Signal:

{
  "ContactKey": "jane.doe@example.com",
  "EventDefinitionKey": "datafly_lead_submitted",
  "Data": {
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+447700900123",
    "lead_type": "newsletter",
    "lead_value": 0,
    "currency": "GBP",
    "user_id": "user-123"
  }
}

Order Completed: events vs data extensions

For order data you have two delivery patterns:

1. Trigger a journey (default) — use this when an order should kick off a post-purchase email, abandoned-cart recovery, or upsell journey. Configure an Event Definition Key for orders and route Order Completed through it.
2. Insert into a Data Extension — use this when you want order rows persisted in Marketing Cloud for reporting or audience building without journey entry. The Data Extension Async API (/data/v1/async/dataextensions/key:{key}/rows) is preferred for this; we plan to ship a separate salesforce_marketing_cloud_data_extensions spec to cover that flow declaratively.

Until the data-extension spec lands, use the journey-trigger flow and pair it with a “no-op” journey that simply records the contact + payload to a Sendable Data Extension.

Testing

1. In Marketing Cloud, open Journey Builder > Events and click the event you bound to Signal.
2. The right-hand panel shows recent fires — Signal events appear within a few seconds of delivery.
3. To trace a specific event, copy the event_id from the Signal event log and search for it in Marketing Cloud’s Tracking view.
4. For end-to-end validation, build a simple test journey with a single “Wait 1 minute > Send Email” path and bind it to your Event Definition Key. Trigger datafly.track(...) and confirm the email arrives.

Rate limits

Marketing Cloud applies tenant-level rate limits to the Interaction API — typically 2,000 events per minute per business unit on standard editions, higher on Enterprise. Signal does not pre-throttle by default; if you expect bursts above this, contact your account team to enable per-integration rate limiting on the integration.

Troubleshooting