Salesforce Marketing Cloud API Essential Guide

What type of API does Salesforce Marketing Cloud provide?

REST API

• Provides broad access to capabilities throughout Marketing Cloud Engagement
• Uses JSON request and response bodies
• Supports multi-channel use cases
• All Marketing Cloud Engagement features implement REST API
• REST calls are synchronous

SOAP API

• Provides comprehensive access to most email functionality
• Uses SOAP envelopes to pass information
• Handles several email-related requirements like tracking, subscribers/lists, automations, triggered sends, content, etc.

Key Considerations

• Both REST and SOAP APIs share a common OAuth2-based authentication mechanism
• You need a client ID and secret from the Installed Packages page to use either API
• The APIs don't have full parity - some use cases may require using both SOAP and REST
• There are usage limits placed on the APIs to ensure availability

Other APIs

Salesforce also offers other specialized APIs like:

• Bulk API for processing large data sets
• Pub/Sub API for asynchronous data streaming
• GraphQL API for efficient querying
• Analytics REST API for working with Analytics data
• Connect REST API for B2B Commerce, CMS content, Experience Cloud sites, etc.

Does the Salesforce Marketing Cloud API have webhooks?

Yes, the official Salesforce Marketing Cloud API does have webhooks through its Event Notification Service (ENS). Here are the key points about the ENS and the types of events you can subscribe to:

Event Notification Service (ENS)

1. The Event Notification Service allows you to receive notifications when certain events occur in Marketing Cloud.

2. It uses webhooks (called callback URLs in Salesforce documentation) to send notifications to your application.

3. To use ENS, you need to set up an API integration with specific permissions, register a callback URL (webhook), and create subscriptions for the events you want to be notified about.

Types of Events You Can Subscribe To

The Event Notification Service supports the following types of notification events:

1. Transactional Email Events
2. Engagement Email Events
3. Transactional SMS Events
4. Engagement OTT Events
5. Transactional OTT Events
6. Automation Studio Events
7. MobilePush Events

Key Considerations

• The ENS is an "at least once" delivery system, so you should prepare your system for the possibility of receiving a notification event more than once.

• You can pause and unpause subscriptions. When unpaused, only new event notifications are delivered, and events that occurred during the pause are dropped.

• The callback URL (webhook) must use HTTPS; HTTP is not supported.

• This feature was primarily created to support the new Transactional API, but it has expanded to include other event types.

It's worth noting that while the ENS supports various event types, it may not cover all possible events in Marketing Cloud. Salesforce continues to develop and expand the capabilities of the ENS, so it's a good idea to check the latest documentation for the most up-to-date information on supported events.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the Salesforce Marketing Cloud API:

Time-based Limits

• There is no absolute limit per day or hour
• For the SOAP API, it's recommended to not exceed 2,000 calls per minute
• For the REST API, Salesforce Support suggests not exceeding 2,500 calls per minute

Yearly Limits

The yearly API call limits depend on the Marketing Cloud edition:

• Basic: 0 calls/year
• Pro: 2 million calls/year
• Corporate: 6 million calls/year
• Enterprise: 200 million calls/year

Additional Considerations

• Marketing Cloud reserves the right to throttle API calls if they impact system performance
• If throttled, you may receive HTTP 500 errors until the issue is resolved
• The REST API has specific error codes (HTTP 429) for too many requests
• There is currently no way to view API usage within Marketing Cloud or via an API call

Best Practices

• Review your contract or contact your Salesforce Account Executive to confirm your exact API limits
• Monitor your API usage to avoid hitting limits
• Implement error handling for rate limit errors (HTTP 429, 500)
• Consider spreading out API calls over time if approaching limits

It's important to note that while there are recommended limits, actual throttling may occur based on system impact rather than strict numerical limits. Proper monitoring and error handling are crucial when working with the Salesforce Marketing Cloud API.

Latest API Version

Based on the search results provided, here is the most up-to-date information about the Salesforce Marketing Cloud API:

Current API Versions

The Salesforce Marketing Cloud offers two main APIs:

1. REST API: Provides broad access to capabilities throughout Marketing Cloud Engagement.
2. SOAP API: Provides comprehensive access to most email functionality.

Most Recent Version

While the search results don't explicitly state the most recent version of the Marketing Cloud API, they provide some relevant information:

• As of April 2021, Marketing Cloud Connect was compatible with version 46.0 of the Sales Cloud and Service Cloud API.
• However, it was noted that at that time, the latest version of the API was 51.0.

It's important to note that this information is from 2021, and the current version may have advanced since then.

Key Points to Consider

• Both APIs (REST and SOAP) share a common authentication mechanism based on OAuth2.
• To use either API, you need a client ID and secret, obtained from the Installed Packages page in Marketing Cloud Engagement Setup.
• The APIs don't have full parity, so some use cases may require using both SOAP and REST to accomplish your business goals.
• There are API usage limits in place to ensure the availability of Marketing Cloud Engagement for all customers.

Best Practices

1. Always check the official Salesforce documentation for the most up-to-date information on API versions.
2. When implementing API calls, use the most recent stable version available to ensure access to the latest features and improvements.
3. Be aware of the differences between REST and SOAP APIs and choose the appropriate one based on your specific use case.
4. Keep track of API usage limits to avoid disruptions in your integrations.

To get the most accurate and current information about the latest API version, it's recommended to consult the official Salesforce Marketing Cloud documentation or contact Salesforce support directly.

How to get a Salesforce Marketing Cloud developer account and API Keys?

Here are the key steps to get a developer account for Salesforce Marketing Cloud to create an API integration:

1. Obtain the necessary permissions:

   • You need the "Installed Package | Administer" permission to create an API integration.
   • This permission is automatically applied to Administrator and Marketing Cloud Administrator roles.

2. Create an installed package:

   • Go to Platform Tools > Apps > Installed Packages in Marketing Cloud.
   • Give the package a name and description.
   • Save the package.

3. Add an API Integration component:

   • In the package details, select "Add Component" and choose "API Integration".

4. Choose the integration type:

   • For most API integrations, select "Server-to-Server".
   • This uses OAuth 2.0 authentication and the client credentials flow.

5. Set the API permissions:

   • Enable the necessary scopes for your integration (e.g. Read/Write access for Contacts).
   • Refer to the Salesforce documentation for required scopes for different API routes.

6. Save the component to generate credentials:

   • The system will generate a client ID and client secret.
   • These credentials are used to authenticate API requests.

7. Securely store the credentials:

   • Never expose the client ID and secret on the client-side or in mobile apps.

8. Use the credentials to obtain an access token:

   • Make a POST request to the token endpoint with your client ID and secret.
   • Use the returned access token to authenticate API calls.

What can you do with the Salesforce Marketing Cloud API?

Here are the key data models you can interact with using the Salesforce Marketing Cloud API, along with what is possible for each:

Subscribers and Lists

• Create, update, delete subscribers
• Add/remove subscribers to/from lists
• Manage subscriber attributes and preferences
• Create and manage subscriber lists
• Retrieve subscriber information and list membership

Email

• Create, send, and manage email campaigns
• Access email tracking and performance data
• Manage email templates
• Schedule email sends
• Trigger transactional email sends

Journeys

• Create and manage customer journeys
• Add/remove contacts from journeys
• Retrieve journey performance metrics
• Pause/resume journeys

Data Extensions

• Create, update, delete data extensions
• Add/update/delete rows in data extensions
• Retrieve data extension information and contents
• Import data into data extensions

Content

• Create and manage content blocks
• Retrieve content assets
• Manage content categories

Automations

• Create and manage automation activities
• Start/stop/schedule automations
• Retrieve automation status and results

Tracking

• Access email open, click, bounce tracking data
• Retrieve web and mobile analytics data
• Access journey and automation tracking

Campaigns

• Create and manage campaigns
• Associate assets with campaigns
• Retrieve campaign performance metrics

Accounts

• Manage account and business unit information
• Retrieve account usage and activity data

Users

• Manage user accounts and permissions
• Authenticate API access

Assets

• Manage files and images
• Upload and retrieve asset content

This covers the major data models accessible via the Marketing Cloud APIs. The exact capabilities may vary between the REST and SOAP APIs, with some functionality only available in one or the other.