Introduction to Triggered Sends

After reading this article you will be able to:

  • Create a triggered email,
  • Create a triggered email interaction,
  • Track and log sent triggered emails,
  • Personalize a triggered email,
  • Trigger an email from Marketing Cloud using various methods,
  • Trigger emails from Sales and Service Cloud.

Understand Triggered Sends in Salesforce Marketing Cloud

A triggered email is a message that Marketing Cloud sends to an individual subscriber in response to a subscriber action. For example, sending a confirmation message after a customer makes a purchase is a triggered email.

A triggered email has two components that you create in Marketing Cloud: content and interaction. When you define a triggered email interaction, you provide information about the message and its behaviour that the interaction uses each time it is triggered, for example: which Sender Profile and Send Classifications to use, which Publication List to use, etc.

The definition of what triggers the interaction to send the email is maintained outside of the application using API calls. The information created in the interface is used by the API when an email is triggered.

Follow the list of step-by-step instruction in this article to create and send your first Triggered Email.

Create an email for use with Triggered Sends

Let’s start by building a very simple email, without any AMPscript or personalization. Go to Email Studio > Content and create an email, just like you would with any other email created in you’re account. Triggered Emails do not have any special requirements when it comes to templates or content blocks used, content types or even where you store them – they’re just like any other emails in Salesforce Marketing Cloud’s Email Studio.

If you need help building an email from scratch, try this link: Create a Content Builder Email.

Create a Triggered Email Message Interaction

Once the email is ready, we can jump to Email Studio > Interactions > Triggered Sends and create a new interaction, which will define all of the Triggered Send’s properties.

In the Triggered Sends section, click on the Create button.

First, let’s define all the properties:

Name is the name or title of this email message interaction. Use this name to identify the message in the application. Subscribers cannot see the name.
External Key is a unique identifier for the message. Use this value to identify the message when using the API. If you leave this field black, the system will automatically generate a key for this interaction upon saving.
Description is a brief explanation of the email’s content and purpose. Subscribers will not see the description.
Send Classification lets you choose a send classification to use for this interaction.
Override Sender Profile determines whether the interaction uses a different sender profile than indicated in the send classification. If selected, select an override sender profile to use.
Override Delivery Profile determines whether the interaction uses a different delivery profile than indicated in the send classification. If selected, select an override delivery profile to use.

In Associate to Campaign section, you can associate the triggered send with a Marketing Cloud Campaign if you have one – if not, leave this section blank.

In the Content section, find and select the email that you created earlier.

In Subscriber Management, there are two separate sections called List and “Triggered Send” Data Extensions.

The purpose of the first one, List, is subscriber management. Either choose All Subscribers or a dedicated publication list if you have one. Failing to select a list results in use of the Triggered Send Managed List, a hidden system-defined List, to track status. Avoid this scenario as the Triggered Send Managed List does not support all triggered send-based functionality.

You will also notice two checkboxes under the List section:

Add subscribers to this list determines whether the list accepts new subscriber information of subscribers who trigger this email interaction. If selected, the send adds the subscriber to a selected list if that email address does not already appear on the list. If, for example, you’re using the All Subscribers list to manage subscriber statuses, and the subscriber who triggers this email interaction is not yet there, they will be added there.

Update Subscribers determines whether an existing subscriber’s attributes should be updated if you pass in new data for that subscriber via the API call.

The “Triggered Send” Data Extensions section lets you choose a Triggered Send Data Extension for use with this interaction, which will act as a SendLog, which means it will update with data from requests to trigger this email interaction. In this section, you can only use a data extension created using the TriggeredSendDataExtension template.

Next, in the Select a suppression list section, you can include a suppression list that prevents certain addresses from receiving triggered email messages, select that list. In the Exclusion Management section, you can use a data extension or exclusion script to prevent email from being sent to selected domains or subscribers. Both those sections are optional, so you can leave them blank if you don’t plan to suppress or exclude anyone.

The last section is also optional and you can choose here any additional Send Options: CC Email Address, BCC Email Address, Track all links found within this email, Send as Multipart MIME, Suppress this Send from Reports. There are also some additional options available (create a support case if they haven’t been enabled in your account):

Priority determines how quickly a triggered email is sent:

  • High – Queued immediately. Using this setting requires an additional cost.
  • Medium – Queued every minute by default. It can take up to 1 minute to send the email.
  • Low – Queued every 5 minutes. It can take up to 5 minutes to send the email.

Keyword categorizes the interaction. If you enter a value in this field, that value is available to API calls.

Send Logging, if checked, logs the send in the SendLog data extension.

The last checkbox, Disable API calls to this triggered send when an email build error threshold is reached, sets a threshold of errors before API calls are disabled and the sending process is stopped. By default, the sending process stops when an error occurs while building an email for a subscriber. These errors can occur for several reasons, including an API call passing in bad data or an AMPscript runtime error. However, the system continues to accept API calls even after an error occurs. If you want to use a back-up system when the threshold is reached, this option allows visibility at the API layer to the error.

Once you are finished, click on the Save button located at the top of the page.

For more information on creating Triggered Email Message Interactions, visit this help article.

Start a Message Interaction

Now that you created and saved your interaction, for the whole setup to go live, we need to “start” it.

From the list of interactions, check the checkbox next to the one you just created and click on the Start/Restart button. Make a note of the External Key, as you will need it later to be able to send the emails out.

If in the future you would need to make some changes to either email content or the interaction properties, such as Sender Profile or Send Classification, pause the interaction first. When it’s paused, it will cause triggered messages to queue while you make all the changes. Publish the interaction to begin sending emails again.

Congratulations, you’re now ready to trigger the first email!

Triggering the email

In order to trigger the email, we will have to interact with Salesforce Marketing Cloud’s SOAP Web Services API. We won’t get into technical details of interacting with the TriggeredSend object, but rather use a couple of code snippets that you will be able to easily copy and paste and use in your instance of Salesforce Marketing Cloud.

Trigger the email using AMPscript

Go to Web Studio > CloudPages, create a new collection and then create a new Landing Page. You can choose to use the Content Builder when creating the landing page, and for the purpose of this demo, you can use a blank page layout. From the Content Blocks available on the left, drag and drop an HTML block onto the canvas and paste the below code into the HTML editor: [click here to see the code on Github]

In the above script, replace ExternalKey with the external key of the interaction you created earlier and replace email@example.com with your email address. Now click on Schedule/Publish in the right upper corner. The script will only take a couple of seconds to execute and a status message will be displayed. In case it’s OK, you can go ahead and check your inbox, as the email should already be there.

To get into more technical details of the above script and learn how to use a Subscriber Key other than the recipient’s email address, read the following article: Send a triggered email using AMPscript.

Trigger the email using WSProxy

WSProxy is a new object for Server-Side JavaScript, introduced by Salesforce in 2018. Using WSProxy has many advantages, about which you can read in this article, Introducing WSProxy for Salesforce Marketing Cloud. The article also explains the benefits of using WSProxy over pure SSJS for sending triggered emails.

Just like we did before, go to Web Studio > CloudPages, create a new collection and then create a new Landing Page. From the Content Blocks menu, drag and drop an HTML block onto the canvas and paste the below code into the HTML editor: [click here to see the code on Github]

In the above script, replace ExternalKey with the external key of the interaction you created earlier, replace email@example.com with your email address, and either provide a SubscriberKey or use your email as SubscriberKey for this demo. Click on Schedule/Publish in the right upper corner. Again, the script will only take a couple of seconds to execute and a status message will be displayed in JSON format. If it shows "Status":"OK", you can check your inbox for the triggered email.

To get into more technical details of the above script, read the following article: Send a triggered email using WSProxy.

Personalizing triggered emails

Triggered emails, just as any other emails sent from Salesforce Marketing Cloud, can be personalized. In order to add personalization to our email, let’s first pause the Triggered Send Interaction, and then go to Email Studio to edit the email. Let’s add a salutation to our email with the subscriber’s first name. There are two ways in which you can achieve this:

  1. In the email, include a simple personalization string, for example: %%firstname%%. This will allow you to pass the firstname value along with the subscriber’s email address and subscriber key, but you will be required to use a “Triggered Send” Data Extensions for your sends and include a column called “firstname” in that Data Extension. The benefit of using this method is that all sends will be recorded in that particular Data Extension and recipient’s first name will be logged along with their email address and other attributes you choose.
  2. In the salutation, include a personalization string using the AMPscript AttributeValue function, for example: %%=v(AttributeValue("firstname"))=%%. This will allow you to pass the firstname value along with the subscriber’s email address and subscriber key, but you won’t be required to use a “Triggered Send” Data Extensions for your sends. The downside of using this solution is that it won’t be logged unless you’re using a regular SendLog which has a column called firstname and you checked the Send Logging option in the Triggered Send Interaction.

After you’ve made all the changes in your email, go back to Email Studio > Interactions > Triggered Sends and first Publish Changes and then Restart the interaction:

Now, let’s go back to our CloudPage and add the additional property, firstname, to our script: [click here to see the code on Github]

Publish the page, and if it shows "Status":"OK", you can check your inbox for the personalized email.

Trigger an email directly from Sales/Service Cloud

NOTE: This feature will only work for Marketing Cloud Connect users and may require Administrator permissions in Sales/Service Cloud.

The process of setting up a Triggered Send in Sales /Service Cloud is similar to using Salesforce Data Entry Event in Journey Builder: we need to choose an object and filter criteria so that the application knows who to send the emails to and under which conditions. Before we configure the Triggered Send, let’s first create a test Campaign in Sales Cloud and activate it, as for the purpose of this demo we will trigger emails to Campaign Member in our test Campaign.

Now let’s make sure that Triggered Sends are enabled for use with Campaign Members in Marketing Cloud Connect. In Sales/Service Cloud, switch to the Salesforce Classic UI, navigate to the Marketing Cloud tab and click on Configure Marketing Cloud Connector. Scroll down to Triggered Sends and in the Enabled Object section, add Campaign Member to the list.

After you save the settings, once again navigate to the Marketing Cloud tab and click on Triggered Sends. In the Triggered Sends Management section, click on New. Enter a Name for your triggered send and choose an Object to use with the Triggered Sends – in this case, a Campaign Member. In Recipient Lookup, choose Lead/Contact and in Filter Criteria, provide the name of the test campaign you created earlier. Next, choose to Trigger send when a new record is created.

Now, let’s find the Email that you created earlier and choose the Send Classification, a Sender Profile if needed and a Triggered Data Extension for logging the send results. Leave the Disable Individual Level Tracking box unchecked, choose immediate Send Time and who the Error Notifications be sent to. Check the box that says I certify all of these people will have opted in and I certify all of these people will have opted in and click on Save.

Now let’s activate the Triggered Send by clicking the Activate button. You’re all set! Now add a Contact or a Lead with your email address to the test Campaign and check your inbox for the Triggered Email.

You will be able to track the results of the Triggered Send in both Sales Cloud and Marketing Cloud: in Sales Cloud, in the Marketing Cloud tab > Triggered Sends and in Marketing Cloud, in Email Studio > Tracking > Triggered Sends.

If you need more information on the above process, refer to this document: Create a Salesforce Triggered Send in Marketing Cloud Connect.

Creating an Apex trigger in Sales Cloud

If upon activating the Triggered Send in Sales/Service cloud you see the following message:

Before activating a triggered send the appropriate Apex Trigger must be created for the following object: CampaignMember

you will need to create an Apex Trigger for the CampaignMember object.

In Sales/Service Cloud, go to Setup. Under Build, click Customize and choose the relevant object – in this case, choose Campaigns > Campaign Members > Triggers. Click on New to create a new trigger, name it Trig_CampaignMember and paste the following code into the editor: [click here to see the code on Github]

Make sure, that in the Apex Trigger window, Is Active checkbox is checked and save it:

Now go back to the Marketing Cloud tab > Triggered Sends and activate your Triggered Send. Once it’s activated, you can start testing!

If you need more information about creating apex triggers for Triggered sends, read this article: Configure Objects and Triggers.


Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Send a triggered email using WSProxy

Triggered sends allow you to automatically send personalized and timely messages to your subscribers. They are sent to an individual subscriber in response to a subscriber action. If you would like to find out more about creating a Triggered Email Message Interaction, check out my other article here.

TriggeredSend object

The TriggeredSend object represents a specific instance of a triggered email send. A typical SOAP envelope consists of the Triggered Send CustomerKey (External Key of the Triggered Email Message Interaction), Subscribers associated with the send and optionally, their Attributes. Here’s an example:

Create a TriggeredSend using WSProxy

WSProxy is a new object for Server-Side JavaScript, introduced by Salesforce in 2018. It acts as a proxy between the Marketing Cloud SOAP Web Service and SSJS. The WSProxy object is native to the platform and simpler to use than the SSJS methods, that’s why it reduces overhead and increases the speed of API calls. WSProxy uses JSON to pass object properties instead of SOAP’s native XML, which makes it much easier to read and write.

To create a new TriggeredSend, we will use the createItem WSProxy function, which has three parameters:

  • The first parameter is the object type to perform the action on – here, we will use previously mentioned TriggeredSend object
  • The second parameter is a JavaScript object which represents the fields and values to set on the object when created – in below example, we will call it tsDef and use it to define the CustomerKey, Subscribers and optionally, their Attributes
  • The third parameter is optional and includes any properties to be set using the SOAP CreateOptions object

Here’s the full script:

In the above script, you will need to provide the Triggered Send External Key and pass an Email Address and Subscriber Key.

If you are using personalization strings in your Triggered Email, you can pass them as name and value pairs in the Attributes object. Here’s an example of passing additional attributes in the WSProxy call:

The results of the call contain three properties from the SOAP CreateResult object: Status, RequestID, and Results. Here’s an example response:

To see how this script works in action, visit the CloudPage that I created and submit your email address here.

Here are additional resources to learn more about Triggered Sends and WSProxy: