Glen Mazza's Weblog

https://glenmazza.net/blog/date/20220906 Tuesday September 06, 2022

Activating Triggered Sends with Marketing Cloud

Marketing Cloud has two primary ways of sending an email. One method involves specifying the email content and a Marketing Cloud list. For these list sends, everyone marked as subscribed on the list will receive the email. A second method, demonstrated here, involves Triggered Sends, in which a triggered email interaction ("TEI") defined in Email Studio is specified along with subscriber(s) to receive an email. While the TEI defines the Content Builder template that will be used in sending the email, attributes defined for each subscriber with the triggered send request can be used by the template to personalize emails. Indeed, if the template itself is largely blank, with the contents defined in those attributes, then each email sent can differ radically for each subscriber.

For both SOAP calls and using the FuelSDK wrapper, the Triggered Send wraps a TriggeredSendDefinition primarily used to identify the TEI that will be sending the emails, along with the Subscribers to be receiving an email. TEIs are created and viewable from Email Studio, menu item Interactions -> Triggered Emails. Links at the bottom provide information on creating TEIs as well as the Content Builder templates that they use.

Briefly, for the below SOAP and Java samples, in Content Builder I created first a template and then a template-based email, with the latter importing the former. For the template, this is what I used:

<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"><title></title></head>
<body>
  <div style="font-size:0; line-height:0;"><custom name="opencounter" type="tracking"><custom name="usermatch" type="tracking" /></div>
  <div data-type="slot" data-key="t81q1twaz2p" data-label="Drop blocks or content here"></div>
  <custom type="footer" />
</body>
</html>
Screenshot showing an email template being edited.

The data-key above (apparently) refers to a specific "enter HTML" widget visible when editing the Template-based email, as shown in the screenshot above. When editing the latter, click on that widget to be able to enter the email-specific content that you see on the left side of the screenshot:

<ctrl:field name="contentHtml"/>
<hr>
This email was sent to %%emailaddr%% by:<br>
%%Member_Busname%%<br>
%%Member_Addr%%<br>
%%Member_City%%, %%Member_State%% %%Member_PostalCode%%<br>
%%Member_Country%%

The plain text version (for subscribers specifying a preference for it) can be entered by clicking on the "Plain Text" area in the screenshot above. Here is what I used:

<ctrl:field name=contentText />

This email was sent to %%emailaddr%% by:
%%Member_Busname%%
%%Member_Addr%%
%%Member_City%%, %%Member_State%%, %%Member_PostalCode%%
%%Member_Country%%

Using the Marketing Cloud Postman workspace, a Sample SOAP request to send an email to two subscribers using a specified TEI would be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <s:Header>
        <a:Action s:mustUnderstand="1">Create</a:Action>
        <a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
        <fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
    </s:Header>
    <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
            <Objects xsi:type="TriggeredSend">
                <Client>
                    <ID>{{et_mid}}</ID>
                </Client>
                <TriggeredSendDefinition>
                    <CustomerKey>external-id-of-TEI</CustomerKey>
                </TriggeredSendDefinition>
                <Subscribers>
                    <SubscriberKey>...one subscriber key...</SubscriberKey>
                    <Attributes>
                        <Name>subject</Name>
                        <Value>Greetings 4!</Value>
                    </Attributes>
                    <Attributes>
                        <Name>contentHtml</Name>
                        <Value>This is &lt;strong>HTML&lt;strong>!</Value>
                    </Attributes>
                    <Attributes>
                        <Name>contentText</Name>
                        <Value>This is plaintext.</Value>
                    </Attributes>
                </Subscribers>
                <Subscribers>
                    <SubscriberKey>...another subscriber key...</SubscriberKey>
                    <Attributes>
                        <Name>subject</Name>
                        <Value>Another email 4</Value>
                    </Attributes>
                    <Attributes>
                        <Name>contentHtml</Name>
                        <Value>This is &lt;em>HTML&lt;em>!</Value>
                    </Attributes>
                    <Attributes>
                        <Name>contentText</Name>
                        <Value>This is in plaintext.</Value>
                    </Attributes>
                </Subscribers>
            </Objects>
        </CreateRequest>
    </s:Body>
</s:Envelope>

Note the attributes attached to the subscriber ("contentHtml", "contentText", etc.) will need to match the attributes used by the TEI's configured email template. For an email to be sent, all attributes referenced by the template must be present for each subscriber in the triggered send.

If there are obvious errors with the SOAP request (for example, not providing any subscribers), the SOAP response coming back normally will identify the problem for you. But if the request appears solid, you'll get the following response that the triggered send was enqueued:

<soap:Body>
    <CreateResponse xmlns="http://exacttarget.com/wsdl/partnerAPI">
        <Results xsi:type="TriggeredSendCreateResult">
            <StatusCode>OK</StatusCode>
            <StatusMessage>Created TriggeredSend</StatusMessage>
            <OrdinalID>0</OrdinalID>
            <NewID>0</NewID>
        </Results>
        <RequestID>...some UUID...</RequestID>
        <OverallStatus>OK</OverallStatus>
    </CreateResponse>
</soap:Body>

This does not guarantee a successful sending of an email, however. From Email Studio, menu item Interactions | Triggered Emails shows completed, queued, and errored counts for each triggered email interaction. If the intended recipient is not getting an email while the error counts for the triggered email interaction keep increasing with each attempt, opening a support ticket with Marketing Cloud, providing them the RequestID above for one of the responses will allow them to search their logs to see what the error is and report back to you.

In Java using the FuelSDK: Java programming involves putting TriggeredSend object(s) into a CreateRequest. The triggered send objects are populated in a similar manner as direct SOAP requests. Sample snippet:

TriggeredSend triggeredSend = new TriggeredSend();
TriggeredSendDefinition tsDef = new TriggeredSendDefinition();
tsDef.setCustomerKey("...external ID of TEI...");
triggeredSend.setTriggeredSendDefinition(tsDef);

Subscriber subscriber = new Subscriber();
subscriber.setSubscriberKey("...subscriber key...");
addAttribute(subscriber, "subject", "email subject line");
addAttribute(subscriber, "contentHtml", "<b>html</b> here");
addAttribute(subscriber, "contentText", "plain text here");
triggeredSend.getSubscribers().add(subscriber);

// Add more subscribers to triggeredSend as desired

CreateOptions options = new CreateOptions();
options.setRequestType(asyncSendsEnabled ? RequestType.ASYNCHRONOUS : RequestType.SYNCHRONOUS);
options.setQueuePriority(Priority.MEDIUM);

CreateRequest request = new CreateRequest();
request.setOptions(options);
request.getObjects().add(triggeredSend);

// configure ETClient similar to here: https://salesforce.stackexchange.com/a/312178
// ETClient etClient = ....
CreateResponse response = etClient.getSoapConnection().getSoap().create(request);
if (!response.getOverallStatus().equalsIgnoreCase("OK")) {
    // success
}

The addAttribute(...) above is just a convenience method:

private void addAttribute(Subscriber s, String name, String value) {
    Attribute a = new Attribute();
    a.setName(name);
    a.setValue(value);
    s.getAttributes().add(a);
}

Further reading:

  1. Official Marketing Cloud documentation on the non-API portions of this process: Create a Triggered Email Message Interaction and Create a Content Builder Email.

  2. Introduction to Triggered Sends - Nice overview of entire process by Zuzanna Jarczynska, which also includes another option of sending a Triggered Email, here using AmpScript on a Cloud Page.

  3. Out of scope for this tutorial, but see here for adding a custom tag to your email template to enable tracking (How many subscribers opened the email, etc.)

Posted by Glen Mazza in Marketing Cloud at 03:00AM Sep 06, 2022 | Comments[0]


Calendar
« September 2022 »
Sun Mon Tue Wed Thu Fri Sat
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Today
About Me
Java Software Engineer
TightBlog project maintainer
Arlington, Virginia USA
glen.mazza at pm dot me
GitHub profile for Glen Mazza at Stack Overflow, Q&A for professional and enthusiast programmers
Blog Search


Blog article index
Links
Baeldung
InfoQ Java
Quintus Curtius
The Lamp
Touchstone Magazine
American Conservative
Modern Age Journal
American Affairs
Recent Posts
Recent Comments
Feeds
Navigation
About Blog
Blog software: TightBlog 4.0.0
Application Server: Tomcat
Database: MySQL
Hosted on: Linode
SSL Certificate: Let's Encrypt
Installation Instructions