Marketing Cloud API

Marketing Cloud API

Use this skill when a task involves calling Marketing Cloud Engagement REST or SOAP APIs from Salesforce Apex, external systems, or integration middleware. It covers OAuth 2.0 authentication via Installed Package credentials, injecting contacts into journeys, firing triggered sends, and upserting rows into Data Extensions. Activate it when you see references to MC API endpoints, journey fire events, or dataeventsasync in the context.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the Marketing Cloud org has an Installed Package with an API Integration component. This is the only supported credential source for OAuth 2.0 client credentials flow. Legacy Fuel (AppCenter) credentials are deprecated.
• Identify the tenant-specific subdomain (also called MID subdomain). All REST and auth endpoints use https://{{subdomain}}.auth.marketingcloudapis.com and https://{{subdomain}}.rest.marketingcloudapis.com. A generic or shared endpoint URL is wrong.
• Know which resource you are targeting: a Journey (needs EventDefinitionKey and the exact entry source field names), a Triggered Send (needs TriggeredSendDefinition ExternalKey and the send must be in Started status), or a Data Extension (needs DE ExternalKey and field names matching DE schema exactly).
• Marketing Cloud REST API has account-level throttling. For bulk operations over ~100 rows, prefer the async endpoint (dataeventsasync) to avoid rate limit errors.

Core Concepts

OAuth 2.0 Client Credentials Flow

Both the REST and SOAP Marketing Cloud APIs require an OAuth 2.0 bearer token. The token is obtained by POSTing to the tenant-specific auth endpoint:

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

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

The response contains access_token (a short-lived JWT, typically 20 minutes), token_type: Bearer, and expires_in. Cache the token and re-acquire only when it expires — do not request a new token for every API call. The token is then passed as Authorization: Bearer {{access_token}} on every subsequent request.

The Client ID and Client Secret come from the API Integration component inside an Installed Package in Marketing Cloud Setup. They are not Salesforce Connected App credentials.

Journey Injection via Fire Entry Event

To inject a contact into a Journey, POST to:

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

{
  "ContactKey": "subscriber@example.com",
  "EventDefinitionKey": "APIEvent-abc123",
  "Data": {
    "FirstName": "Jane",
    "AccountTier": "Gold"
  }
}

Critical: The field names inside Data must exactly match the field names configured on the journey's entry source schema — including case. If a field name is wrong or missing, the API returns HTTP 201 (Created) but the contact is silently dropped from the journey with no error. There is no retry or error callback.

EventDefinitionKey is found in Journey Builder under the journey's entry source settings, not the Journey's own key. These are different values.

Triggered Sends

Triggered sends require a three-step lifecycle:

1. Create a TriggeredSendDefinition via SOAP API or Marketing Cloud Setup UI, specifying the email, subscriber list, and ExternalKey.
2. Start the definition (status must be Active / Running). Sending against a definition in Draft status returns an error.
3. Fire the send via REST:

   POST https://{{subdomain}}.rest.marketingcloudapis.com/messaging/v1/messageDefinitionSends/key:{ExternalKey}/send
   

   with a payload containing the subscriber's To.Address and To.SubscriberKey, plus any profile attribute substitutions.

Data Extension Row Operations

Two patterns exist for writing rows to a Data Extension:

• Synchronous upsert (up to ~100 rows per call, recommended for real-time use cases):

  POST /hub/v1/dataevents/key:{ExternalKey}/rowset
  

  Blocks until rows are committed. Returns 200 on success.

• Asynchronous bulk insert (preferred for > 100 rows or high-volume batch jobs):

  POST /hub/v1/dataeventsasync/key:{ExternalKey}/rowset
  

  Returns immediately with a requestId. Poll GET /hub/v1/dataeventsasync/{requestId} to confirm completion. Use this pattern when throughput matters more than immediate confirmation.

Common Patterns

Pattern: Apex Callout for Journey Injection

When to use: Salesforce Apex code needs to fire a contact into a Marketing Cloud journey after a record change (e.g., Opportunity stage change triggers onboarding journey).

How it works:

1. Store Client ID, Client Secret, and subdomain in a Custom Metadata Type or Named Credential (never hardcode).
2. Make an Apex HttpRequest to the token endpoint; parse the access_token from the JSON response.
3. Build the journey injection payload with the correct EventDefinitionKey and Data object using the exact field names from the entry source schema.
4. POST to /interaction/v1/events with the bearer token.
5. Check the HTTP response code. A 201 means the request was accepted — not that the contact entered the journey. Log the response body for debugging.

Why not a simple callout without token caching: Each token request counts against API call limits. In a trigger or batch context, acquiring a new token per record will exhaust limits quickly.

Pattern: Async DE Row Upsert for Bulk Sync

When to use: A nightly batch or platform event processor needs to sync hundreds or thousands of Salesforce records into a Marketing Cloud Data Extension.

How it works:

1. Batch records into chunks of up to 2,000 rows per request (check current limit in official docs).
2. POST each chunk to dataeventsasync endpoint and store the returned requestId.
3. After all chunks are submitted, poll each requestId until status is Complete or Error.
4. Log errors and implement retry logic only for Error status responses.

Why not the synchronous endpoint: The sync endpoint blocks the Apex thread and can time out on large datasets. The async endpoint decouples submission from confirmation and is the documented pattern for bulk operations.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Confirm credentials and endpoints: Retrieve the Client ID, Client Secret, and tenant-specific subdomain from the Installed Package API Integration component. Verify the subdomain format is {{MID}}.auth.marketingcloudapis.com — not a generic URL.
2. Acquire an OAuth 2.0 token: POST to the /v2/token endpoint with grant_type=client_credentials. Parse and cache access_token and expires_in. Implement token refresh logic so the token is re-acquired before expiry, not on every call.
3. Identify the target resource: For journeys, locate the EventDefinitionKey from the entry source settings (not the journey key). For triggered sends, confirm the TriggeredSendDefinition exists and is in Active status. For DEs, confirm the DE ExternalKey and retrieve the field schema.
4. Build the request payload: Match field names exactly to the target resource schema. For journey injection, every field in Data must match entry source field names case-sensitively. For DE row operations, include all required fields or upsert will fail silently.
5. Make the API call and handle the response: A 201 for journey injection means accepted, not confirmed entry. A requestId from async DE insert requires polling. Log the full response body — Marketing Cloud error messages are in the body, not always in the status code.
6. Validate end-to-end: In Marketing Cloud, check Journey Builder contact history or DE row count to confirm records are processed, not just accepted.

Review Checklist

Run through these before marking work in this area complete:

• Credentials come from an Installed Package API Integration component — not hardcoded, not Legacy Fuel
• Token is cached and refreshed before expiry, not requested per API call
• Journey injection payload uses the EventDefinitionKey from the entry source, not the journey key
• All field names in Data object exactly match the entry source schema (case-sensitive)
• TriggeredSendDefinition is in Active/Started status before firing sends
• Bulk DE operations use async endpoint and poll the requestId for completion status
• API responses are logged; errors from Marketing Cloud appear in response body, not only HTTP status codes

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Journey injection silently drops contacts on field name mismatch — If any field name in the Data object does not exactly match the entry source schema (including case), the API returns HTTP 201 but the contact never enters the journey. There is no error message and no retry. This is the most common cause of "contacts not entering the journey" bugs.
2. TriggeredSendDefinition must be Started before firing — Creating the definition is not enough. The definition must be explicitly started (status Active). Firing a send against a Draft definition returns an error, but the error message is not always obvious that status is the cause.
3. Tenant-specific subdomain is mandatory — generic endpoints fail — Marketing Cloud REST API endpoints are always tenant-specific: https://{{subdomain}}.rest.marketingcloudapis.com. Using a generic URL or the wrong tenant subdomain results in authentication failures or 404 errors that look like network issues.

Output Artifacts

Related Skills

• admin/marketing-cloud-connect — use when configuring the CRM connector between Salesforce core and Marketing Cloud (not API-based integration)
• integration/soap-api-patterns — use when the integration requires SOAP API patterns in Salesforce core (not Marketing Cloud SOAP)
• integration/oauth-flows-and-connected-apps — use when managing OAuth flows for Salesforce core Connected Apps (not MC Installed Package credentials)