Marketing Integration Patterns

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:

• What is the latency requirement? Triggered Sends target sub-second delivery for single messages; Journey Injection is near-real-time but involves Journey processing overhead; SFTP batch is typically 15–60 minute latency depending on Automation Studio schedule.
• What is the integration initiator — an external non-Salesforce system, Salesforce core (Sales/Service Cloud), or an internal Marketing Cloud process?
• Does the contact need to receive a single transactional message, or be enrolled in a multi-step Journey with decision logic?
• What is the daily contact volume and peak burst rate? Async batch via Event API accepts up to 100 contacts per request; SFTP file drops handle millions of records.
• Does the Installed Package with API Integration exist in Marketing Cloud? Every REST API pattern requires this — there is no workaround.

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

Recommended Workflow

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:

• Installed Package with API Integration exists; clientId and clientSecret are stored securely (not in code)
• OAuth 2.0 token acquisition uses the tenant-specific auth endpoint, not a generic or hardcoded URL
• Access token is cached and refreshed before 20-minute expiry; no per-call re-authentication
• Triggered Send Definition is in Active status before the integration goes live
• Journey Injection uses eventDefinitionKey from the REST API Entry Source, not Journey ID
• Async batch calls do not exceed 100 contacts per request
• SFTP file column headers match Data Extension field API names exactly
• Error handling covers HTTP 401 (token expiry), 429 (rate limit), and 500-range errors
• Transactional send classifications are verified to bypass commercial subscription preferences correctly
• MC Connect SDEs are used instead of custom API calls when Salesforce CRM is the data source

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

Related Skills

• apex/marketing-cloud-api — Use when implementing the Apex-side callout to Marketing Cloud REST endpoints from Salesforce core; covers token management and callout patterns in Apex
• admin/marketing-cloud-connect — Use when configuring the MC Connect CRM connector between Salesforce core and Marketing Cloud (Synchronized Data Extensions, Connected App setup)
• architect/sales-cloud-integration-patterns — Use when the integration involves Sales Cloud objects as the data source and the destination is not Marketing Cloud

Official Sources Used

• Marketing Cloud REST API Overview — https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rest-api.html
• Marketing Cloud API Integration (Installed Package) — https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/mc-create-an-installed-package.html
• Fire Entry Event (Journey Injection) — https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/postEvent.html
• Insert Contacts Async (Batch Journey Injection) — https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/postEventAsync.html
• Triggered Send Definition REST API — https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/messageDefinitionSends.html
• Salesforce Well-Architected Overview — https://architect.salesforce.com/docs/architect/well-architected/guide/overview.html