Use REST API Across Marketing Cloud Engagement

Learning Objectives

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

Describe how to use the Marketing Cloud Engagement REST API.
Identify the Marketing Cloud Engagement apps that interface with the REST API.

Take a REST

Marketing Cloud Engagement’s REST API offers you access to the most recent Marketing Cloud Engagement features. This unit gives you insight into what you can accomplish with the REST API and how to customize it to your needs.

REST API Basics

Before we dive in, take a look at the common traits for all REST API requests and endpoints.

The REST API supports multichannel use and accepts JSON request bodies.
All requests are synchronous and can contain up to 4 MB of information.
Tracking information and other data-retrieve operations time out after 300 seconds.
Other requests time out after 120 seconds.

With that in mind, let’s take a look at what you can accomplish with the REST API across several Marketing Cloud Engagement apps.

Content Builder

In Marketing Cloud Engagement, Content Builder is where you can create all of the material included in email, push, and SMS messages. No matter how the information is sent from the account, all of the content (also known as assets) resides in Content Builder. Assets also include the templates and slots used to create and organize your content.

You can use REST API requests to retrieve, update, or delete assets and categories (also known as folders) in Content Builder, among other less common requests. Salesforce Developers contains a full list, including samples of requests and resources to use when interacting with Content Builder.

Example: Update an Email Message

Take a look at the following resource and organization for a request. This example updates an existing email message, and it also demonstrates a typical JSON payload. The request uses the PATCH method to the specified route and updates the content of an email message. The ID value accepts the external key used to identify the asset in your account.

PATCH /asset/v1/content/assets/{id}
{
 "name": "NTO Welcome Series Email",
 "channels": {
   "email": true,
   "web": false
},
 "views": {
   "html": {
     "content": "<!DOCTYPE html><body>This is a simple message.</body></html>"
 },
 "text": {},
 "subjectline": {},
 "preheader": {}
 }
}

Journey Builder

Journey Builder determines how contacts receive different types of messages based on events and behavior. For example, you can send email messages to customers who signed up for a newsletter, but never clicked a link or purchased a product. This is an example of a journey. To create a journey in Marketing Cloud Engagement, your steps can look something like this example.

Create a sendable data extension in Marketing Cloud Engagement. This data extension includes a unique contact key for each contact and information to use as part of any send.
Create event definitions in Marketing Cloud Engagement. These event definitions control which contacts enter the journey and when.
Build the journey. This includes any activities, such as sends or updates, that determine which messages the contact receives. You can also add a goal here to help you determine the success of the journey.
Publish the journey. This step activates the journey and evaluates contacts to determine if they enter the journey.
Fire an entry event. This step begins the journey for the contacts that meet the entry criteria.

A journey can include some pretty complex operations, so Salesforce Developers includes a full reference for all these steps.

Example: Send an Email Message Via Journey Builder

Let’s take a look at a simple example, for reference. Here’s the JSON for an event that sends an email message. The information specifies the activity and the triggered send with associated metadata. The email is sent when the event is triggered as part of the journey.

{
   "type": "EMAILV2",
   "key": "<activity key>",
   "name": "<activity name>",
   "applicationId": "<Marketing Cloud Engagement provided GUID>",
   "outcomes": [
      {
        "key": "<outcome key>",
        "next": "<key of next activity>"
      }
   ],
   "metaData":{
      "icon":"/img/email-icon.svg",
      "iconSmall":"/img/email-icon.svg",
      "category":"message",
      "version":"1.0",
      "isConfigured":true
   },
   "configurationArguments":{
      "triggeredSend":{
        "emailId":"<email id>",
        "emailSubject": "<subject>",
        "preHeader":"<preheader>",
        "description":"<description>",
        "campaigns":[
            {
               "id":"<campaign id>",
               "name":"<campaign name>",
               "color":"<campaign color>"
            }
   ],
   "sendClassificationId":"<send classification id>",
   "senderProfileId":"<sender profile id>",
   "deliveryProfileId":"<delivery profile id>",
   "publicationListId":"<publication list id>",
   "suppressionLists":[
       {
          "name":"<suppression list name>",
          "id":"<suppression list id>"
       }
   ],
   "domainExclusions":[
       {
          "name":"<domain exclusion name>",
          "id":"<domain exclusion id>"
       }
   ],
   "exclusionFilter":"<exclusion script>",
   "isTrackingClicks":true,
   "isMultipart":true,
   "isSendLogging":true,
   "suppressTracking":true,
   "ccEmail":"<cc email>",
   "bccEmail":"<bcc email>",
   "keyword":"<keyword>",
   "throttleLimit":500,
   "throttleOpens":"12:00",
   "throttleCloses":"12:30",
   "isSalesforceTracking":true
       }
   }
}

GroupConnect

Marketing Cloud Engagement uses the GroupConnect REST API to send messages using apps like Facebook Messenger and LINE. Contacts might receive messages for shipping or reservation updates, account changes, or other communications.

You can set up your GroupConnect API integration with these steps from Salesforce Developers.

Example: Register a Facebook Page

This example contains a sample request that identifies the platform, includes the necessary access information, and identifies the page to register.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /ott/v1/registration
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
    "ottPlatformName" : "messenger",
    "ottPlatformAttributes" : {
       "applicationId" : "1093076390764037",
       "applicationSecret" : "03d537gg656gvkbe9b430f002e9c4517",
       "pageId" : "1732555047025799",
       "pageName" : "SFMC Engineers",
       "pageAccessToken" :
"someaccesstoken4fasdcruib213123knubkdnfisdubnu12312ub3pijnb",
       "endpointUrl" :
"https://graph.facebook.com/v2.6/me/messages",
       "callbackVerifyToken" : "this_is_the_verify_token",
       "isActive": true
    }
}

MobileConnect

MobileConnect allows Marketing Cloud Engagement accounts to send SMS and MMS messages to contacts. These types of messages require more regulation than email messages, so MobileConnect provides different types of opt-in mechanisms to help you comply with the applicable regulations for your sends. All contacts must opt to receive your messages in one of three ways.

Single Opt-In. The contact sends an SMS message via a short code to subscribe to further communication.
Double Opt-In. The contact sends the SMS message and confirms in a reply that they want to continue receiving messages.
Double Opt-In with Age Confirmation. In addition to the two confirmation messages, the contact also confirms that they are old enough to receive the messages.

After they’ve subscribed, you can send a variety of messages to your subscribers, either individually or via a list. You can also create triggered messages that send after a certain activity, such as a purchase or shipment. Other common API requests include subscription confirmation and using a web form (or mobile app) as part of the opt-in process.

Example: Send an SMS Message Via MobileConnect

Let’s take a look at an example for sending a message to welcome a new subscriber. The Subscribe and Resubscribe values require subscription confirmation before sending the message.

POST
https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com/sms/v1/messageContact/MzA6Nzg6MA/send
Content-Type: application/json
Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN
{
   "mobileNumbers": [
   "13175551212"
   ],
   "Subscribe": true,
   "Resubscribe": true,
   "Override": true,
   "messageText": "Welcome to Salesforce Developers",
}

Personalization Builder

Personalization Builder works with Einstein Recommendations to personalize multichannel messages based on your customers’ needs, interests, and preferences. This API integration helps you update the information used to create recommendations, manage privacy requests, and download large reports.

This integration requires the Crimson Kraken API key from your Marketing Cloud Engagement account. Contact your Marketing Cloud Engagement admin for assistance if you can’t access this key.

Example: Update Personalization Builder Settings

This example shows an example of information necessary to update privacy settings for the specified Personalization Builder profile.

Host:  https://app.igodigital.com
POST /api/v2/organization/12345678/privacy
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
{
   "batch": {
      "hashed-id-01": ["do_not_track"], // Adds "do_not_track" privacy setting, removes "do_not_profile" or "do_not_process" if they were previously set
      "hashed-id-02": ["do_not_profile"], // Adds "do_not_profile" privacy setting, removes "do_not_track" or "do_not_process" if they were previously set
      "hashed-id-03": ["do_not_process"], // Adds "do_not_process" privacy setting, removes "do_not_profile" or "do_not_track" if they were previously set
      "hashed-id-04": ["do_not_track", "do_not_profile"], // Adds "do_not_track" and "do_not_profile" privacy settings, removes "do_not_process" if it was previously set
      "hashed-id-05": ["do_not_track", "do_not_process"], // Adds "do_not_track" and "do_not_process" privacy settings, removes "do_not_profile" if it was previously set
      "hashed-id-06": ["do_not_profile", "do_not_process"], // Adds "do_not_profile" and "do_not_process" privacy settings, removes "do_not_track" if it was previously set
      "hashed-id-07": ["do_not_track", "do_not_profile", "do_not_process"], // Adds "do_not_track", "do_not_profile" and "do_not_process" privacy settings
      "hashed-id-08": [], // Removes any existing privacy settings for profile
      "hashed-id-09": ["rtbf_delete"], // Deletes profile and associated data
      "hashed-id-10": ["rtbf_suppress"] // Deletes profile and associated data after suppression period
   }
}

Transactional Messaging

The transactional messaging API manages automated messaging used for order confirmations, password resets, and other nonpromotional messages. You can use email or SMS messages for these communications. This API offers speedier performance than your average triggered send in Email Studio or MobileConnect, and you can use the Event Notification Service (an immediate notification API) to receive instantaneous confirmation of your sends.

To create transactional messages using the API, follow these steps.

Create an email message in Content Builder and a list in Email Studio (or a keyword in MobileConnect).
Get your access token.
Create a transactional send definition via REST API. If you create a triggered send in Email Studio or Outbound Message in MobileConnect, the transactional REST API fails to send.
(Optional) You can create a subscription using the Event Notification Service that delivers real-time tracking data about the messages.

Example: Send a Transactional Email Message

This sample code contains an example of the information necessary to send a transactional email message.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /messaging/v1/email/messages/f4fe74b7-c3c0-4e5a-9f49-b63a641109a2
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
  "definitionKey": "2FA_order_accounts",
  "recipient":
  {
   "contactKey": "recipient2",
    "to": "recipient2@example.com",
    "attributes": {
      "UserAttribute_1": "value_1",
      "UserAttribute_n": "value_n",
    }
  },
}

Whew, we covered a lot! And that’s just the start of what’s possible with the REST API. You can find additional resources and explore even more possibilities on Salesforce Developers. Next up, you learn how to amp up your Email Studio integration with the SOAP API.