To understand more about Transactional Email API, it is important to understand the concept of Triggered Sends.Please feel free to have a look at my previous blog on how to send a triggered email in cloud page via ampscript.
Problem Statement:
Every second matters when it comes to Transactional emails! If you have used Triggered Send for real time emails, you will understand the pain of Marketing Cloud emails arriving late to your inbox. If you set a medium priority, it typically takes 2 minutes for the email to arrive, whereas if you set a high priority you will receive the email in under a minute, but also consume 4 super messages! On face value this may seem acceptable, but over time you will easily reach the super message limit.
To solve this problem, Salesforce Marketing Cloud released a new feature last year (2019) called “Transactional Messaging API’s”, where Emails & SMS will both be sent in near real time (max around 5-10 seconds) whilst consuming just 1 super message!
Interesting right?! Let’s take a look at the difference between Triggered Sends and Transactional Email API, helping you choose which one to progress with.
Triggered Sends Vs Transactional API:
Advantages of Triggered Sends:
Multiple Options for exclusion - You can exclude/suppress contacts through various means, such as by adding them to an Exclusion Data Extension, adding them to a Suppression List, or adding AMPscript within the exclusion script.
You can view the Trigger send definition in UI - Let’s say you want to update your email content. You could do this in Content Builder, pause, publish your changes, and restart the triggered send definition. The emails will update automatically with your new content.
Disadvantages of Triggered Sends:
It will take around 2 minutes to actually receive the email using a medium priority Trigger Definition, and as discussed prior, setting this to High will lead to faster delivery, but also consume 4 super messages.
It won’t give you the email tracking status which has been sent from Triggered email. -For example, let’s say if you have sent an email to bounced contact you will have to identify only via tracking. There is no automatic tracking for handling bounces.
Advantages of Transactional Email API:
Transactional Email API will send emails in near real time (5 to 10 sec maximum). It’s a synchronous API, and noticeably faster than Triggered Sends.
For example, you need to send an important transactional email to a customer, such as a reservation confirmation and the Marketing Cloud API’s are down indefinitely. In this instance, you would receive an error from the API, and resolve the issue by trying to send the email out with other applications like Salesforce or Sendgrid.
We can leverage event notification services provided by Salesforce Marketing cloud.
Using this service enables you to track bounces, opens & clicks by passing the message definition key, storing the records and creating dashboards from the external system. We will cover this in upcoming blogs.
Disadvantages of Transactional API Email:
API is not available in UI.
If you wanted to change any content within your emails, as well as changes to the sender profile, you would need to make these changes via API only. Unlike Triggered Sends, you can’t see it anywhere in the UI.
Exclusion is not possible
Let's take a use case, wherein you can create multiple profile with single email address but you should receive only one email for your first profile creation and shouldn't receive any other email for next profile creation. In this case exclusion will be difficult from Transactional API email. You would need some middleware to check if it's already created. If created then don’t call the Transactional API endpoints.
This should give you an idea of when a triggered send is appropriate to use, and conversely when to use transactional API’s.
Let’s Get started on Transactional Email API:
Scenario: We will take a simple use case- a customer filling out a sign-up form. Once completed, we would need to send a verification email to check if he/she has provided us with a valid email address.
Step 1: Create a Triggered Data extension to Store the Transactional API Values:
Go to Email Studio > Email > Subscribers > Data Extensions > Choose a folder > Click on Create > Standard Data Extension > Choose Create method as ‘Create from Template’ and Choose Triggered send data extension > Give a name for Data extension.
Let’s call it ‘Test_Transactional_API’.
For this demo, add 2 more fields (First Name and Last Name).
Below is a screenshot for your reference:
Step 2: Create a simple form in Cloud Page:
Go to Web Studio > Cloud Pages > Create a new Cloud Page > Create it via Content builder > Give it a name > Click create > Drag and Drop the Free Form / HTML content Block and paste the below code [View Full Code]:
*Make sure the input tag name properly matches with Data Extension field/attribute names.*
Step 3: Create an Installation Package:
In order to access Marketing cloud API’s, you need to create an installation package.
Please follow the official Salesforce help documentation to create an installation package with an API Integration component.
Step 4: Create Transactional API Definition:
This is a one time activity, in which we need to create a definition to tie together the Transactional Sender Profile, the Triggered Send Data Extension, and the email we are going to be sending.
You can accomplish this in REST API Tools such as ‘PostMan’.
Make an authentication Call in Postman [view full code]:
Use this access token to perform the next API call in Postman to create a Transactional API definition.
You can use the official Salesforce help document as a guide to see how the definition is created via API:
Below is a screenshot showing our definition in Postman.
Step 5: Create data extension for creating unique message key
To send a single send to a contact using Transactional Email API, you would need to have a unique message key. To accomplish this, we can store and increment the most recent value used.
Let’s call the Data Extension ‘Test_Transactional_API_Counter’
You can add other use cases on separate rows.
Note: If you are planning to include multiple sends in a single call out, then you don’t need a unique message Id. Here is the reference link for sending multiple emails in a single call out.
Step 6: Create a Data Extension to store the response logs from Transactional API:
Let’s call this Data Extension ‘Test_Transactional_API_Logs’
Step 7 : Add Changes to Cloud Page to send a Transactional API Email:
Below is the full code for the cloud page where you can add in the cloud page and just change the Definition key [View Full Code]:
Decoding the Code:
On clicking submit, we are authenticating Marketing Cloud and obtaining the access token.
Using the access token, we are calling on another API to help send our email from Marketing Cloud.
We need a unique ID on the API, so we are storing the previous value in the ‘Test_Transactional_API_Counter’ Data Extension and incrementing the values.
Once we call the API, it will return a response log which we are capturing in the ‘Test_Transactional_API_Logs’ Data Extension
If you are planning to implement event notification service check out my post on implementing event notification service using cloud page as callback URL.
Update 06/08/2020: As part of July 2020 release, you can directly create and maintain Transactional emails in journey builder instead doing it via API. Here is the reference document.
I hope this article helps you in getting started with Transactional Email Messaging in Cloud Pages!
Please feel free to let your thoughts.
Happy Learning! Share the Salesforce!
Content Editor and Proof Reader - Stephen Izod