Skip to main content
Build the future with Agentforce at TDX in San Francisco or on Salesforce+ on March 5–6. Register now.

Explore Developer Tools

Learning Objectives

After completing this unit, you’ll be able to:

  • Explain the differences between the Marketing Cloud Engagement REST and SOAP APIs.
  • Describe how you can use the Marketing Cloud Engagement SDKs.
  • Name the Marketing Cloud Engagement programmatic languages.

Introduction

So you’re a Marketing Cloud Engagement developer. Whether you’ve been doing this a while, or learning it for the first time, we want to introduce you to the wealth of tools at your fingertips for extending the power of Marketing Cloud Engagement. Trailblazers like you are making a huge impact with Salesforce customers around the globe—whether you’re a consultant doing custom development for multiple customers, or an in-house developer creating custom solutions for your employer. From SDKs to APIs, we’ll give you enough information in this module to get started with Marketing Cloud Engagement development, so you’re ready to use the tools you need for your next project.

A developer sitting at a desk with her laptop and a light bulb over her head to indicate an idea.

Note

Want to meet more Trailblazers? Check out their stories on Trailhead.

Marketing Cloud Engagement APIs

Ready to get started with Marketing Cloud Engagement APIs? In this module, we assume you understand the basics about APIs (application programming interfaces) and how they are used for communication between two different software applications. If you haven’t worked with APIs before, that’s okay. In this badge, we’re looking at the Marketing Cloud Engagement APIs at a high level, so you can understand their differences and how you can use them.

So let’s dive into Marketing Cloud Engagement APIs. The first thing to know is that Marketing Cloud Engagement offers two APIs: REST (Representational State Transfer) and SOAP (Simple Object Access Protocol). Both of these APIs are used for distinct purposes. The REST API exposes broader access to Marketing Cloud Engagement capabilities. The SOAP API provides comprehensive access to most email functionality. These two APIs share a common authentication mechanism based on OAuth 2. Let’s take a closer look at each.

REST API

The REST API for Marketing Cloud Engagement is a great way to share assets from your internal databases or applications with your Marketing Cloud Engagement account. 

Here are some examples of what you can do:

Marketing Cloud Engagement REST API
 What you use it for...
Content Builder
 Share marketing content, such as emails, images, text, and other documents.
Event Notification Service
 Receive notifications when certain events occur in Marketing Cloud Engagement. You can be notified when customers request password resets, get order confirmations, log in using two-factor authentication, and other events.
Journey Builder
 Create event-driven, responsive campaigns to distribute across any channel (online and offline), at any time and at any frequency.
GroupConnect Chat Messaging
 Send real-time event-based messages to your users in Facebook Messenger and LINE.
MobileConnect API
 Subscribe mobile numbers to a short code using one of three SMS opt-in variations.
Personalization Builder
 Update the data used to provide Einstein recommendations, manage consumer privacy requests, and easily download large reports.
Transactional Messaging
 Send personalized, transactional email messages to your customers.

All new Marketing Cloud Engagement technologies implement REST API, so this is an important one to familiarize yourself with. Here are a few important things to note about the Marketing Cloud Engagement REST API:

  • The REST API uses JSON (JavaScript Object Notation) request and response bodies and resource endpoints to support multi-channel use.
  • Most REST calls are synchronous.
  • Timeout values are 120 seconds for non-tracking operations and 300 seconds for tracking and data retrieve operations.
  • The maximum payload of any call is four megabytes.

SOAP API

As you know, SOAP APIs provide a means for applications on different operating systems, technologies, and languages to communicate using only XML. You can use the Marketing Cloud Engagement SOAP API for managing things such as tracking data, subscribers and lists, automations, content, and most other email activities. 

Here’s some examples of what you can do:

Web Services SOAP API
 What you use it for...
Send Email
 Schedule and send emails, identifying message recipients using dynamic, rule-based segmentation of lists, events and profiles.
Tracking
 Retrieve tracking data and use it to create reports and dashboards to see how your customers view and respond to your data.
Subscribers and lists
 Retrieve subscribers for a list or lists for a subscriber.
Automations
 Define an activity using an automation in Automation Studio.
Triggered Send
 Create a triggered email send.

Keep these things in mind when using the Marketing Cloud Engagement SOAP API:

  • The SOAP API uses SOAP envelopes to pass information between you and Marketing Cloud Engagement.
  • We recommend a limit of no more than 2000 per minute for SOAP calls.
  • Support may request your SOAP envelope to troubleshoot issues.

Marketing Cloud Engagement SDKs

Looking for SDKs (Software Development Kits) to develop custom applications you can use with Marketing Cloud Engagement? You’re in luck! Marketing Cloud Engagement SDKs provide a cross-functional framework around the SOAP and REST APIs, allowing you to integrate APIs using native language code libraries. The Marketing Cloud Engagement platform SDKs use both the SOAP and REST APIs to provide agnostic protocol interfaces and automated token management. In addition to SDKs for the Marketing Cloud Engagement platform, we offer SDKs for MobilePush and Content Builder. 

We currently offer platform SDKs for C#, Java, Node, PHP, and Ruby. Check out example code for a few of these:

Platform
 Code Sample of the SDK being used to retrieve all lists in an account
C# SDK
 using FuelSDK;
ET_Client client = new ET_Client();
ET_List request = new ET_List();
request.AuthStub = client;
GetReturn response = list.Get();
Console.WriteLine(response.Status.ToString());
PHP SDK
 require('sdk/ET_Client.php');
$client = new ET_Client();
$request = new ET_List();
$request->authStub = $client;
$response = $request->get();
print_r($response);
Ruby SDK
 require 'fuelsdk'
client = FuelSDK::Client.new {'client' => { 'id' => YOUR_CLIENT_ID, 'secret' => YOUR_CLIENT_SECRET }}
request = FuelSDK::List.new
request.client = client
response = list.get
p response

We also provide SDKs for iOS and Android to use with MobilePush, a Marketing Cloud Engagement product that allows you to create and send targeted push messages based on cross-channel consumer data to encourage app usage.

The Salesforce Marketing Cloud Engagement SDKs, excluding the MobilePush and Content Builder SDKs, are community-supported projects. The SDK source code, samples, and documentation are publicly available on Github to use as-is or fork and modify for your needs. We invite everyone in the community to collaborate with us on Github and submit pull requests to help improve the source code and samples. 

Marketing Cloud Engagement Programmatic Languages

Marketing Cloud Engagement offers custom scripting languages to personalize landing pages, create applications, construct cross-channel templates or layouts, and work with messaging functions on the Marketing Cloud Engagement platform.

AMPscript

AMPscript is a scripting language that you can embed within HTML emails, text emails, landing pages, SMS messages, and push notifications from MobilePush. Do you want a message to display customized text to the recipient? For example, “Thanks for your purchase, Ted, you earned 1,000 points as a Gold subscriber!” AMPscript is your answer for personalization. Marketing Cloud Engagement processes the AMPscript calls at the time of send.

Server-Side JavaScript (SSJS)

Marketing Cloud Engagement uses JavaScript code processed by Marketing Cloud Engagement servers. Instead of using the browser to render the JavaScript on the client-side computer, Marketing Cloud Engagement executes the JavaScript on the server when rendering. While you can duplicate the functionality of AMPscript using SSJS, SSJS doesn’t work with the Document Object Model (DOM) and doesn’t function with exterior libraries. In other words, you can use these functions to modify Marketing Cloud Engagement content, but not browser-based things like JavaScript. Instead, use libraries provided by Marketing Cloud Engagement to create SSJS that works. These libraries also allow updates to SSJS, while maintaining previous versions, to avoid breaking preexisting code. 

Wondering whether to use AMPscript or SSJS? Consider this:

  • AMPscript is the preferred language for personalizing message content. It simply and efficiently handles inline personalization or simple IF ELSE statements.
  • AMPscript works better than SSJS for use cases where each subscriber needs to see unique content.
  • AMPscript has a shorter learning curve than SSJS for users new to scripting languages in general.
  • A great number of people already know JavaScript and can immediately apply that knowledge to Marketing Cloud Engagement.
  • Most users can handle the tasks they need to perform using AMPscript.

We recommend that you exclusively use AMPscript or Platform object server-side JavaScript functions in email messages and reserve your use of Core library server-side JavaScript to landing pages and applications where AMPscript doesn’t provide appropriate functions.

Guide Template Language (GTL)

GTL provides a declarative syntax used for creating personalized, dynamic, data-driven messages, as well as constructing cross-channel templates and layouts. GTL uses the widely adopted Handlebars and Mustache template languages and provides additional functionality, while simplifying how users interact with content and data to help them quickly build personalized Journey messages. GTL works with JSON data sources supplied by script or by a REST API service. Guide can also access specified lists and data extensions within a Marketing Cloud Engagement account.

Resources

Share your Trailhead feedback over on Salesforce Help.

We'd love to hear about your experience with Trailhead - you can now access the new feedback form anytime from the Salesforce Help site.

Learn More Continue to Share Feedback