Salesforce Marketing Cloud — Data Integration

Salesforce Marketing Cloud (SFMC) has two different API types in use: a Rest API and a SOAP API. Within the Python ecosystem, a library called FuelSDK integrates with the Salesforce Marketing Cloud APIs. With it, it is possible to integrate directly with SFMC. It is also possible to use automation within Salesforce Marketing Cloud to pick up data from an FTP here; however, I will focus on data integration using SFMC’s REST API.

Pushing data to Salesforce Marketing Cloud usually happen in two flavors:

• A call to a data extension endpoint
• A call to a trigger send endpoint.

A data extension in SFMC is a data repository backed by a MS SQL backend. It is normally used in SFMC to provide the right type of journeys for automated journeys.

The trigger send endpoint is responsible for updating your contact information with the new information, providing the data to a data extension, and trigger an email. It is usually used for transactional style of emails that need to be processed right away.

Authorization:

Authorization with the salesforce marketing cloud rest API can be done through an Oauth2 request token call:

def auth(clientId: str, clientSecret: str ) -> requests.Response: end_point = “https://auth.exacttargetapis.com/v1” + “/requestToken” headers = {‘Content-type’: ‘application/json’} payload = { “clientId”: clientId, “clientSecret”: clientSecret, “accessType”: “offline” } req = requests.post( end_point, headers=headers, data=json.dumps(payload) ) return req

The response is in the following JSON format and contains an access token. This token is valid for a limited period of time, but a new access token can be requested again using either the clientId and Secret or the refresh token.

{ “accessToken”:”1ZbHNgf4mGDYV22D82x3WvZY”, “expiresIn”:3479, “refreshToken”:”5ZbTNgf3mGV2V22D82x3WvVY” }

Data Extension

Using the rest API data events endpoint, it is possible to upload multiple mini-batch events to the salesforce marketing cloud. There is a limitation of 5MB to push and a recommendation to only send up to 50 rows at a time.

def post_to_data_extension( accessToken: str, dataExtensionKey: str, items: list ) -> requests.Response: host = “https://www.exacttargetapis.com” end_point = “/hub/v1/dataevents/key:{key}/rowset” url = host + end_point.format(key=dataExtensionKey) headers = { “Content-Type”: “application/json”, “Authorization”: “Bearer %s” % accessToken } data = items req = requests.post( url, headers=headers, data=json.dumps(data) ) return req

Trigger Send

Trigger sends work in a similar way to data extension endpoints but has different payloads that need to be provided. It contains a field Subscriber attributes that can be used to provide the data necessary to a data extension or contact update.

def post_to_trigger_send( accessToken: str, triggeredSendDefinitionKey: str, SubscriberKey: str, From: dict, Attributes: dict ) -> requests.Response: host = “https://www.exacttargetapis.com” end_point = “/messaging/v1/messageDefinitionSends/key:{triggeredSendDefinitionKey}/send” url = host + end_point.format(triggeredSendDefinitionKey=triggeredSendDefinitionKey) headers = { “Content-Type”: “application/json”, “Authorization”: “Bearer %s” % accessToken } data = { “From”: From, “To”: { “Address”: SubscriberKey, “SubscriberKey”: SubscriberKey, “ContactAttributes”: { “SubscriberAttributes”: Attributes } }, “Options”: { “RequestType”: “ASYNC” } } req = requests.post( url, headers = headers, data=json.dumps(data) ) return req

an example call can then be:

post_to_trigger_send( myaccessKey, “test_email_send”, “julienkervizic@myfakeemailaddress.com”, { “Address”: “julienkervizic@myfakeemailaddress.com”, “Name”: “Julien@Original Sender” } , { “orderId”: “order123”, “content”: “Testing The Content of this message” } )

With 202 accepted response in the following format:

{ “requestId”:”c222dcpc-j40d-423l-8125-79b296fh69ad”, “responses”:[ { “recipientSendId”:”c222dcpc-j40d-423l-8125-79b296fh69ad”, “hasErrors”:false, “messages”:[“Queued”] } ] }

Once the trigger send has been processed, it will update the required contact and data extension depending on the configuration set up in Salesforce Marketing Cloud.

Email Delivery Status

When generating async trigger sends call when often want to get some insight on the status. The SFMC Rest API support these kinds of calls:

def get_email_delivery_status( accessToken: str, key: str, RecipientSendId: str ) -> requests.Response: host = “https://www.exacttargetapis.com” end_point = “/messaging/v1/messageDefinitionSends/key:{key}/deliveryRecords/{RecipientSendId}” url = host + end_point.format(key=key,RecipientSendId=RecipientSendId) headers = { “Content-Type”: “application/json”, “Authorization”: “Bearer %s” % accessToken } req = requests.get( url, headers=headers ) return req

With the following type of response being provided on sent success:

{ “deliveryTime”:”2018-07-09T16:40:33.69″, “id”:”2dzf2a6c-b833-e811-a2cb-1401fc8c5d2d”, “messageId”:”c222dcpc-j40d-423l-8125-79b296fh69ad”, “status”:”Sent”, “to”:{ “address”:”julienkervizic@myfakeemailaddress.com”, “id”:12345, “key”:”julienkervizic@myfakeemailaddress.com” } }

Providing data to SFMC using its Rest API is straightforward. Setting up the different calls in python allows to set up recurring jobs easily using tools such as Airflow.