SfSkills Domains Docs GitHub

Home / architect / marketing-integration-patterns

marketing-integration-patterns

Use when designing or selecting an integration pattern between Marketing Cloud and an external system or Salesforce CRM — including Triggered Sends, Journey injection via Event API, async batch contact entry, SFTP file-based batch sync, and MC Connect Synchronized Data Extensions.

Open the skill folder on GitHub

Marketing Integration Patterns

Use this skill when choosing and designing how an external system — an e-commerce platform, CRM, ERP, or mobile backend — sends data to or triggers messaging in Marketing Cloud. The skill covers the three primary real-time patterns (Triggered Sends, Journey Injection via Event API, and async batch contact entry), batch file-based sync via SFTP and Automation Studio, and near-real-time CRM sync via MC Connect Synchronized Data Extensions. All patterns require authentication setup through an Installed Package with API Integration.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Installed Package and OAuth 2.0 Client Credentials

Every Marketing Cloud REST API integration requires an Installed Package with an API Integration component configured in Marketing Cloud Setup. The API Integration issues a clientId and clientSecret. All calls must first authenticate via the Marketing Cloud authentication endpoint to obtain a short-lived Bearer token:

POST https://<tenant-specific-subdomain>.auth.marketingcloudapis.com/v2/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<clientId>",
  "client_secret": "<clientSecret>"
}

The response includes an access_token (valid 20 minutes) and a rest_instance_url for subsequent REST calls. Tokens must be cached and refreshed before expiry — do not re-authenticate on every request. The Installed Package must have the correct scopes enabled: at minimum Email > Send Email for Triggered Sends, and Journeys > Execute for Journey Injection.

Triggered Sends — Transactional Single-Message REST

A Triggered Send Definition (TSD) is a pre-configured send definition in Marketing Cloud that pairs a template, data extension, and send classification. External systems call the REST endpoint to fire a single message to a single subscriber immediately. The TSD must be in Active status before calls will succeed.

The call pattern is:

POST https://<rest_instance_url>/messaging/v1/messageDefinitionSends/key:<ExternalKey>/send
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "To": {
    "Address": "customer@example.com",
    "SubscriberKey": "sub-12345",
    "ContactAttributes": {
      "SubscriberAttributes": {
        "FirstName": "Jane",
        "OrderNumber": "ORD-9988"
      }
    }
  }
}

Triggered Sends are best for transactional messages: order confirmations, password resets, shipping notifications. They bypass subscription preferences for commercial sends only when the send classification is set to Transactional. The external key (key:<ExternalKey>) references the TSD's External Key field, not its internal ID.

Journey Injection via Event API — Multi-Step Enrollment

The Event API (also called the Journey Builder Entry Event API) injects one or more contacts into a Journey as entry events. The Journey must have a REST API-based Entry Source configured, and that Entry Source generates an eventDefinitionKey. The eventDefinitionKey is what the external system passes — not the Journey ID, not the Journey name, and not the Entry Source name.

The call pattern is:

POST https://<rest_instance_url>/interaction/v1/events
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "ContactKey": "sub-12345",
  "EventDefinitionKey": "APIEvent-abc123-def456",
  "Data": {
    "EmailAddress": "customer@example.com",
    "ProductCategory": "Electronics",
    "CartValue": "149.99"
  }
}

A single call enrolls one contact. For batch injection of up to 100 contacts, use the async batch endpoint:

POST https://<rest_instance_url>/interaction/v1/events/async

The async endpoint accepts a "contacts" array with up to 100 entries per request and returns a requestId for polling. There is no synchronous batch; individual /events calls are synchronous but rate-limited.

SFTP File Drop with Automation Studio Import Activity

For high-volume batch sync (initial loads, nightly CRM exports, daily audience refreshes), the canonical pattern is:

  1. External system writes a CSV file to the Marketing Cloud SFTP location (/import/ folder or a custom path).
  2. An Automation Studio automation monitors the SFTP folder via a File Drop trigger or runs on a schedule.
  3. An Import Activity picks up the file, maps columns to a Data Extension, and imports contacts using an "Add and Update" or "Overwrite" import mode.
  4. Downstream activities (SQL Activity, Send Activity) execute after import completes.

This pattern handles millions of records per file and is the correct choice for bulk initial loads or nightly audience sync. It is not appropriate for latencies under 15 minutes.

MC Connect Synchronized Data Extensions

When the data source is Salesforce Sales Cloud or Service Cloud (not a third-party system), Marketing Cloud Connect enables Synchronized Data Extensions (SDEs). SDEs are read-only replicas of Salesforce objects (Contact, Lead, Account, Campaign, CampaignMember, custom objects) that Marketing Cloud polls and refreshes on a configurable schedule (default: 15 minutes for standard, near-real-time for configured objects).

SDEs allow Journey Builder to use Salesforce CRM data as entry criteria and personalization attributes without a custom API integration. This is the recommended pattern for CRM-to-Marketing-Cloud data flow when the org has Marketing Cloud Connect installed and configured.

Common Patterns

Real-Time Transactional Email via Triggered Send

When to use: An external system (e-commerce checkout, password reset service, booking confirmation engine) needs to send a single personalized transactional email to a specific subscriber immediately after an event.

How it works:

  1. Create a Triggered Send Definition in Marketing Cloud Email Studio with a Content Builder template. Set the Send Classification to Transactional.
  2. Set the TSD status to Active.
  3. Configure an Installed Package with API Integration. Enable the Email > Send Email scope.
  4. External system authenticates via OAuth 2.0 client credentials to obtain a Bearer token.
  5. POST to /messaging/v1/messageDefinitionSends/key:<ExternalKey>/send with subscriber attributes in the request body.
  6. Marketing Cloud fires the message immediately. The response includes a requestId and HTTP 202 if accepted.

Why not the alternative: Using Journey Injection for single transactional messages adds unnecessary Journey processing latency and complexity. Journey Injection is for enrolling contacts in multi-step sequences, not one-shot transactional sends.

Journey Enrollment from External E-Commerce System

When to use: An e-commerce platform detects a cart abandonment, product view, or purchase event and needs to enroll the customer in a Marketing Cloud Journey (welcome series, abandonment re-engagement, post-purchase nurture).

How it works:

  1. Build the Journey in Journey Builder with a REST API Entry Source. Note the auto-generated eventDefinitionKey from the Entry Source configuration screen.
  2. Configure an Installed Package with API Integration. Enable Journeys > Execute scope.
  3. E-commerce platform triggers an event (cart abandoned, order placed).
  4. Platform backend authenticates to Marketing Cloud via OAuth 2.0 client credentials.
  5. POST to /interaction/v1/events with the ContactKey, EventDefinitionKey, and any data attributes needed for Journey personalization.
  6. For bulk events (up to 100 contacts), POST to /interaction/v1/events/async with a contacts array.
  7. Journey Builder processes the entry and routes the contact through the Journey steps.

Why not the alternative: Triggered Sends cannot branch or apply decision logic. Journey Injection is necessary when the message sequence depends on subscriber behavior or attributes evaluated within the Journey.

Nightly Batch Audience Sync via SFTP

When to use: An external data warehouse, ERP, or CRM exports a daily audience file (potentially millions of rows) to refresh a Marketing Cloud Data Extension used for segmentation or campaign sends.

How it works:

  1. External system generates a UTF-8 CSV file with headers matching the target Data Extension field names.
  2. File is placed on the Marketing Cloud SFTP server in the designated /import/ path using SFTP credentials from Marketing Cloud Setup.
  3. An Automation Studio automation with a File Drop trigger (or scheduled trigger) detects the file.
  4. An Import Activity maps the file columns to the Data Extension and runs with "Add and Update" mode to upsert records.
  5. Subsequent automation steps (SQL Activity for segmentation, Send Activity) execute after import.

Why not the alternative: Calling the Data Extension REST API row by row for millions of records is impractical — the REST API has rate limits and per-call overhead. SFTP import is the only scalable path for bulk data loads.

Decision Guidance

SituationRecommended PatternReason
Single transactional message triggered by an external event (order confirmation, password reset)Triggered Send via REST API (/messaging/v1/messageDefinitionSends/key:<key>/send)Lowest latency, simplest payload, designed for single-subscriber transactional sends
Enroll contact in multi-step Journey from external systemJourney Injection via Event API (/interaction/v1/events)Entry API is the only way to inject contacts into an active Journey with dynamic data
Batch inject up to 100 contacts into a Journey in one callAsync Event API (/interaction/v1/events/async)Async endpoint accepts contact arrays; synchronous endpoint is single-contact only
Nightly or scheduled bulk audience sync (millions of records)SFTP file drop + Automation Studio Import ActivityOnly pattern that scales to millions of records without API rate-limit constraints
Salesforce CRM (Sales/Service Cloud) data to Marketing CloudMC Connect Synchronized Data ExtensionsNative CRM connector; no custom API code; refreshes on schedule or near-real-time
Initial contact data load for a new Marketing Cloud orgSFTP file drop + Import Activity with Overwrite modeBulk load; no need for real-time latency during initial setup

Step-by-step instructions for an AI agent or practitioner designing a Marketing Cloud integration:

  1. Classify the integration trigger and latency requirement — Determine whether the external system needs immediate single-message delivery (Triggered Send), Journey enrollment (Event API), or batch sync (SFTP). Latency, volume, and message complexity drive the pattern choice.
  2. Check Installed Package exists and has correct scopes — Every REST API pattern requires an Installed Package in Marketing Cloud Setup with an API Integration component. Confirm the clientId and clientSecret are available and that the correct permission scopes are enabled for the chosen pattern.
  3. Locate or create the target artifact — For Triggered Sends: confirm the Triggered Send Definition is Active and note its External Key. For Journey Injection: confirm the Journey has a REST API Entry Source and note the eventDefinitionKey (not the Journey ID). For SFTP: confirm the Data Extension schema matches the expected file columns.
  4. Implement OAuth 2.0 token acquisition with caching — Authenticate using the tenant-specific auth endpoint. Cache the access_token and refresh before expiry (tokens live 20 minutes). Do not re-authenticate on every API call — this causes rate limit errors.
  5. Implement the integration call with the correct endpoint and payload — Use the tenant-specific rest_instance_url returned in the auth response (not a hardcoded URL). For async batch, poll the returned requestId for status. Handle HTTP 429 (rate limit) with exponential backoff.
  6. Test with edge cases — Verify behavior when the subscriber does not exist in the All Subscribers list (creation vs. rejection), when the TSD is in Inactive status, and when the eventDefinitionKey is incorrect. Document the failure modes.
  7. Validate error handling and alerting — Ensure non-2xx responses are logged, retried where appropriate, and surfaced as alerts. Triggered Sends and Journey Injection are fire-and-forget from the caller's perspective — silent failures require explicit monitoring.

Review Checklist

Run through these before marking work in this area complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Journey Injection requires eventDefinitionKey, not Journey ID — The Journey Builder REST API Entry Source generates a UUID-like eventDefinitionKey (e.g., APIEvent-abc123-def456). Using the Journey ID or Entry Source name in the payload will produce a 400 error with a misleading error message. The key is visible in the Entry Source properties panel in Journey Builder.
  2. Async batch endpoint cap is 100 contacts per request — not a soft limit — The /interaction/v1/events/async endpoint returns a 400 error if the contacts array exceeds 100 entries. There is no automatic batching. Callers must split payloads into chunks of ≤ 100 before sending.
  3. All patterns require Installed Package with API Integration — there is no alternative auth method — Marketing Cloud REST APIs do not accept username/password authentication or session-based auth. Any integration without a properly configured Installed Package will fail at the token acquisition step. This is a common gap when teams assume the Marketing Cloud FTP credentials or SOAP credentials will work for REST calls.
  4. Triggered Send Definition must be Active — Inactive or Paused TSDs return 400, not 404 — If the TSD is paused or inactive, the API returns a 400 Bad Request with no clear indication that a status change is needed. Validate TSD status programmatically before every deployment or build a monitoring check.
  5. SFTP Import Activity column mapping is case-sensitive and header-exact — If the CSV header is EmailAddress and the Data Extension field API name is email_address, the import will fail silently — records are skipped rather than rejected with a clear error. Always verify Data Extension field API names against the file headers before configuring the Import Activity.
  6. MC Connect Synchronized Data Extensions are read-only in Marketing Cloud — SDEs cannot be written to from Marketing Cloud — they are CRM-sourced replicas. Attempts to use them as writeable data targets in SQL Activities or import flows will fail. Use standard writable Data Extensions for Marketing Cloud-generated data.

Output Artifacts

ArtifactDescription
Integration pattern recommendationSelected pattern (Triggered Send, Journey Injection, Async Batch, SFTP, MC Connect) with rationale matched to latency and volume requirements
Authentication setup checklistInstalled Package configuration steps, required scopes, and token caching implementation guidance
API endpoint referenceExact endpoint URL pattern, HTTP method, required headers, and example payload for the chosen pattern
Error handling specificationHTTP status codes to handle, retry policy, dead-letter strategy, and monitoring approach
Data flow diagramVisual showing external system event through to Marketing Cloud message or data entry point

Official Sources Used

Dependencies

Package files