Learning Objectives /Objectifs de formation
After completing this unit, you’ll be able to: /Une fois cette unité terminée, vous pourrez :
- Describe how to use the Marketing Cloud REST API. /Décrire comment utiliser l’API REST Marketing Cloud.
- Identify the Marketing Cloud apps that interface with the REST API. /Identifier les applications Marketing Cloud qui s’interfacent avec l’API REST.
Take a REST/Choisir REST API
Marketing Cloud’s REST API offers you access to the most recent Marketing Cloud features. /L’API REST de Marketing Cloud vous permet d’accéder aux fonctionnalités les plus récentes de Marketing Cloud.
This unit gives you insight into what you can accomplish with the REST API and how to customize it to your needs. /Cette unité vous donne un aperçu de ce que vous pouvez accomplir avec l’API REST et comment le personnaliser selon vos besoins.
REST API Basics /Principes de base de l’API REST
Before we dive in, take a look at the common traits for all REST API requests and endpoints. /Avant de commencer, jetons un coup d’œil aux caractéristiques communes à toutes les demandes et points de terminaison de l’API REST.
- The REST API supports multichannel use and accepts JSON request bodies. /L’API REST prend en charge l’utilisation multicanal et accepte les demandes écritent en code JSON.
- All requests are synchronous and can contain up to 4 MB of information. /Toutes les demandes sont synchrones et peuvent contenir jusqu’à 4 Mo d’informations.
- Tracking information and other data-retrieve operations time out after 300 seconds. /Les informations de suivi et les autres opérations de récupération de données expirent après 300 secondes.
- Other requests time out after 120 seconds. /Les autres demandes expirent après 120 secondes.
With that in mind, let’s take a look at what you can accomplish with the REST API across several Marketing Cloud apps. /Dans cet esprit, voyons ce que vous pouvez accomplir avec l’API REST sur plusieurs applications Marketing Cloud.
Content Builder / Générateur de contenu
In Marketing Cloud, Content Builder is where you can create all of the material included in email, push, and SMS messages. /Dans Marketing Cloud, Content builder est le lieu de création de tous les templates tel que email, push et des messages SMS.
No matter how the information is sent from the account, all of the content (also known as assets) resides in Content Builder. /Quelle que soit la façon dont les informations sont envoyées à partir du compte, tout le contenu (également connu comme créas) réside dans content builder.
Assets also include the templates and slots used to create and organize your content. /Les créas incluent également les modèles et les emplacements utilisés pour créer et organiser votre contenu.
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. /Vous pouvez utiliser des demandes d’API REST pour récupérer, mettre à jour ou supprimer des créas et des catégories (également appelés dossiers) dans Content Builder, entre autres demandes moins courantes.
Salesforce Developers contains a full list, including samples of requests and resources to use when interacting with Content Builder. /Salesforce Developers contient une liste complète, y compris des exemples de demandes et de ressources à utiliser lors de l’interaction avec Content Builder.
Example: Update an Email Message / Exemple: mettre à jour un e-mail
Take a look at the following resource and organization for a request. /Jetez un œil à la ressource et à l’organisation suivantes pour une demande.
This example updates an existing email message, and it also demonstrates a typical JSON payload. /Cet exemple met à jour un e-mail existant et illustre également une utilisation JSON typique.
The request uses the PATCH method to the specified route and updates the content of an email message. /La demande utilise la méthode PATCH vers la direction spécifiée et met à jour le contenu d’un e-mail.
The ID value accepts the external key used to identify the asset in your account. / La valeur ID accepte la clé externe utilisée pour identifier la créa dans votre compte.
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. /Journey Builder détermine comment les contacts reçoivent différents types de messages en fonction des événements et du comportement.
For example, you can send email messages to customers who signed up for a newsletter, but never clicked a link or purchased a product. /Par exemple vous pouvez envoyer des emails aux clients qui se sont inscrits à une newsletter, mais qui n’ont jamais cliqué sur un lien ou acheté un produit.
This is an example of a journey. /Ceci est un exemple de journey.
To create a journey in Marketing Cloud, your steps can look something like this example. /Pour créer un parcours dans Marketing Cloud, vos étapes peuvent ressembler à cet exemple.
1-Create a sendable data extension in Marketing Cloud. This data extension includes a unique contact key for each contact and information to use as part of any send. /Créez une extension de données pouvant être envoyée dans Marketing Cloud. Cette extension de données comprend une clé de contact unique pour chaque contact et des informations à utiliser dans le cadre de tout envoi
2-Create event definitions in Marketing Cloud. These event definitions control which contacts enter the journey and when. /Créez des définitions d’événements dans Marketing Cloud. Ces définitions d’événements contrôlent quels contacts entrent dans le parcours et quand.
3-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. /Construisez le parcours. Cela inclut toutes les activités, telles que les envois ou les mises à jour, qui déterminent les messages que le contact reçoit. Vous pouvez également ajouter un objectif ici pour vous aider à déterminer le succès du parcours.
4-Publish the journey. This step activates the journey and evaluates contacts to determine if they enter the journey. /Publiez le parcours .Cette étape active le parcours et évalue les contacts pour déterminer s’ils entrent dans le parcours.
5-Fire an entry event. This step begins the journey for the contacts that meet the entry criteria. /Déclenchez un événement d’entrée. Cette étape débute le parcours pour les contacts qui répondent aux critères d’entrée.
A journey can include some pretty complex operations, so Salesforce Developers includes a full reference for all these steps. /Un parcours peut inclure des opérations assez complexes, la documentation Salesforce développeurs contient une référence complète pour toutes ces étapes.
Example: Send an Email Message Via Journey Builder /Exemple: envoyer un e-mail via Journey Builder
Let’s take a look at a simple example, for reference. /Voyons un exemple simple d’une référence.
Here’s the JSON for an event that sends an email message. /Voici le JSON d’un événement qui envoie un e-mail.
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. /Les informations spécifient l’activité et l’envoi déclenché avec les métadonnées associées. L’e-mail est envoyé lorsque l’événement est déclenché dans le cadre du parcours.
{
"type": "EMAILV2",
"key": "<activity key>",
"name": "<activity name>",
"applicationId": "<Marketing Cloud 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 uses the GroupConnect REST API to send messages using apps like Facebook Messenger and LINE. /Marketing Cloud utilise l’API REST GroupConnect pour envoyer des messages à l’aide d’applications telles que Facebook Messenger et LINE.
Contacts might receive messages for shipping or reservation updates, account changes, or other communications. /Les contacts peuvent recevoir des messages pour l’envoi ou les mises à jour de réservation, les changements de compte ou d’autres communications.You can set up your GroupConnect API integration with these steps from Salesforce Developers. /Vous pouvez configurer votre intégration API GroupConnect à l’aide de ces étapes à partir de la documentation Salesforce développeurs.
Example: Register a Facebook Page /Exemple: enregistrer une page Facebook
This example contains a sample request that identifies the platform, includes the necessary access information, and identifies the page to register. /Cet exemple contient un exemple de requête qui identifie la plateforme, inclut les informations d’accès nécessaires et identifie la page à enregistrer.
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 accounts to send SMS and MMS messages to contacts. / MobileConnect permet aux comptes Marketing Cloud d’envoyer des messages SMS et MMS aux 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. /Ces types de messages nécessitent plus de réglementation que les e-mails, MobileConnect propose donc différents types d’Opt-In vous aider à vous conformer aux réglementations applicables à vos envois. Tous les contacts doivent choisir de recevoir vos messages de trois manières.
1-Single Opt-In. The contact sends an SMS message via a short code to subscribe to further communication. /Opt-in unique.Le contact envoie un SMS via un code court pour s’abonner à une communication ultérieure.
2-Double Opt-In. The contact sends the SMS message and confirms in a reply that they want to continue receiving messages. /Double opt-in. Le contact envoie le message SMS et confirme dans une réponse qu’il souhaite continuer à recevoir des messages.
3-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. /Double opt-in avec confirmation d’âge. En plus des deux messages de confirmation, le contact confirme également qu’ils sont l’âge requis pour recevoir les messages.
After they’ve subscribed, you can send a variety of messages to your subscribers, either individually or via a list. /Une fois qu’ils se sont abonnés, vous pouvez envoyer divers messages à vos abonnés, individuellement ou via une liste.
You can also create triggered messages that send after a certain activity, such as a purchase or shipment. /Vous pouvez également créer des messages déclenchés qui sont envoyés après une certaine activité, comme un achat ou une expédition.
Other common API requests include subscription confirmation and using a web form (or mobile app) as part of the opt-in process. /D’autres demandes d’API courantes incluent la confirmation de l’abonnement et l’utilisation d’un formulaire Web (ou d’une application mobile) dans le cadre du processus d’adhésion.
Example: Send an SMS Message Via MobileConnect /Exemple: envoyer un message SMS via MobileConnect
Let’s take a look at an example for sending a message to welcome a new subscriber. /Voyons un exemple d’envoi d’un message pour souhaiter la bienvenue à un nouvel abonné.
The Subscribe and Resubscribe values require subscription confirmation before sending the message. /Les valeurs d’abonnement et de réabonnement nécessitent une confirmation d’abonnement avant d’envoyer le 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 /Générateur de personnalisation
Personalization Builder works with Einstein Recommendations to personalize multichannel messages based on your customers’ needs, interests, and preferences. /Personalization Builder fonctionne avec les recommandations Einstein pour personnaliser les messages multicanaux en fonction des besoins, des intérêts et des préférences de vos clients.
This API integration helps you update the information used to create recommendations, manage privacy requests, and download large reports. /Cette intégration d’API vous aide à mettre à jour les informations utilisées pour créer des recommandations, gérer les demandes de confidentialité et télécharger des rapports volumineux.
This integration requires the Crimson Kraken API key from your Marketing Cloud account. Contact your Marketing Cloud admin for assistance if you can’t access this key. /Cette intégration nécessite la clé API Crimson Kraken de votre compte Marketing Cloud. Contactez votre administrateur Marketing Cloud pour obtenir de l’aide si vous ne pouvez pas accéder à cette clé.
Example: Update Personalization Builder Settings /Exemple: mise à jour des paramètres du générateur de personnalisation
This example shows an example of information necessary to update privacy settings for the specified Personalization Builder profile. /Cet exemple montre un exemple d’informations nécessaires pour mettre à jour les paramètres de confidentialité pour le profil Personalization Builder spécifié.
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 / Messagerie transactionnelle
The transactional messaging API manages automated messaging used for order confirmations, password resets, and other nonpromotional messages. /L’API de messagerie transactionnelle gère la messagerie automatisée utilisée pour les confirmations de commande, les réinitialisations de mot de passe et d’autres messages non promotionnels.
You can use email or SMS messages for these communications. /Vous pouvez utiliser des messages email ou SMS pour ces 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. /Cette API offre des performances plus rapides que votre envoi déclenché moyen dans Email Studio ou MobileConnect, et vous pouvez utiliser le service de notification d’événements (une API de notification immédiate) pour recevoir une confirmation instantanée de vos envois.
To create transactional messages using the API, follow these steps. /Pour créer des messages transactionnels utilisant l’API, suivez ces étapes
- Create an email message in Content Builder and a list in Email Studio (or a keyword in MobileConnect). /Créez un e-mail dans Content Builder et une liste dans Email Studio (ou un mot-clé dans MobileConnect).
- Get your access token. /Récupérer votre jeton d’accès.
- 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. /Créez une définition d’envoi transactionnel via l’API REST. Si vous créez un envoi déclenché dans Email Studio ou un message sortant dans MobileConnect, l’API REST transactionnelle ne parvient pas à envoyer.
- (Optional) You can create a subscription using the Event Notification Service that delivers real-time tracking data about the messages. /(Facultatif) Vous pouvez créer un abonnement à l’aide du service de notification d’événements qui fournit des données de suivi en temps réel sur les messages.
Example: Send a Transactional Email Message /Exemple: envoyer un e-mail transactionnel
This sample code contains an example of the information necessary to send a transactional email message. /Cet exemple de code contient un exemple des informations nécessaires pour envoyer un e-mail transactionnel.
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. /Ouf, nous avons fait le plein de connaissance! Et ce n’est qu’un début des possibilités de l’API REST. Vous trouverez des ressources supplémentaires et encore plus de possibilités sur Salesforce Developers. Prochainement, vous verrez comment amplifier votre intégration via Email Studio avec l’API SOAP.
Resources /Ressources
- Salesforce Developer: Intro to Marketing Cloud APIs
- Salesforce Developer: Content Builder API
- Salesforce Developer: GroupConnect Chat Messaging API
- Salesforce Developer: Journey Builder API
- Salesforce Developer: MobileConnect API
- Salesforce Developer: Personalization Builder API
- Salesforce Developer: Transactional Messaging API
- Salesforce Developer: REST API Reference
