Marketing Cloud - Send email via API

Question

I am completely new to salesforce. I am developing an application that is supposed at some point to send emails through salesforce marketing cloud, using their APIs.

I've found about triggers and transactional messages, but I'm not sure if these two are the right way to do it.

I was wondering if there's a more simple and better way to send an email using salesforce APIs, both using an already existing template on salesforce or using a template written from scratch in HTML.

Answer 1

I will do my best to provide you with guidance, more than an answer. Why? Your question touches many more topics than just the API. Let me explain.

You will be able to use Transactional Messaging API in Marketing Cloud to trigger emails from your application. Before being able to perform successful calls, you will need to take care of few prerequisites:

1. You will need a set of credentials (client ID and client Secret) for authenticating your API calls. I will recommend you to go through this Trailhead module explaining basics of SFMC APIs.
2. You must create en email in Content Builder within Marketing Cloud. Most common approach is to have 95% or the HTML static, and use Ampscript to fetch data from your API payload for presonalization (e.g. Hi %%first_name%%).
3. Before you create your Transactional send in Journey Builder, you will need to decide what fields you want to pass in your payload. These need to be added to a Transactional Send Data Extension, as they will be stored as a snapshot for every API call.
4. You must understand the concept of Contact Key in Marketing Cloud, as it is used as a unique identifier of each email recipient, and should be consistent across all the data sources referencing the particular recipient. This Identifier must be passed in your API call, along withe recipient's email address.
5. Once you have gone through all the above steps, you should be ready to go. Let's check the list again, just to be on the safe side:

• Client ID, Client Secret, Tenant specific endpoint, business unit ID for authentication
• Email created with relevant Ampscript for personalisation
• Triggered Send Data extension ready with all the needed fields (in addition to Email Address and Subscriber Key) for holding data fields from your API call payload
• Transactional Email journey created and activated - this one basically links the email with the data extension, and provides a unique key for your API call to address, ensuring the right journey will be triggered.

This should have you covered, for sending your first API triggered email from SFMC.

But Lukas, can't I pass the full email body in my API payload?

Theoretically, yes. It will not be elegant and against best practice (E.g. none of your links will be trackable). Before you can do so, you must create a Triggered Send data extension with a field to store ALL your HTML code. It must be more than the max limit of 4000 characters (you can bypass this by leaving the length-field empty when creating your data extension in Email Studio). And your email message in Content Builder should basically be empty and only consist of a single variable, printing the HTML from that single payload field.

Answer 2

The best way to send emails from Marketing Cloud(MC) would be to have data in MC, build the audience there and trigger the emails in MC, but that works only when you have something like a daily send. If you are using data that is hosted outside of MC or you have a dynamic trigger, like immediately after a client clicks a button, then you will need to use an API Call to trigger the send.

To do this is pretty easy. You don't need to create the email or the journey/campaign using the MC APIs, you can use an MC Team (Developers, Consultants, Designers, etc.) to do all this for you and will tell you more about how to trigger the email send action using the APIs. Your only job should be implementing the code for the email trigger.

You have two main ways/endpoints for triggering an email send (there are other ways but these ones from REST API are the easiest to use):

1. Transactional API
2. Fire Event API

The Transactional API is used for sending transactional emails only, while the Fire Event API is used to start a Journey that can have multiple activities.

To trigger either of them is simple, you need to authenticate first to get the Access Token and using that Token you can start triggering email sends. For both APIs you will need the DefinitionKey of the Journey (this is mapped to the email that you want to send and will be provided by MC developers), the unique identifier of the customer (based on whatever ID is your system using: an email address, a GUID, a auto-number, etc.), the email address to which you want to send that email and the personalization data used in the email body (First Name, OrderId, etc.)

The exact API that you need to use for the triggering of the email: the endpoint, a payload example and response examples can be found in the MC Documentation.

For Transactional API Single Recipient

For Transactional API Multiple Recipients

For Fire Event API Single Recipient

For Fire Event API Multiple Recipients

I would recommend the use of the Multiple Recipients version to avoid hitting the MC recommendation/limit for the number of API Calls per minute, but this is something that needs to be decided based on your business requirements and needs.

To sum it up, to trigger an email sent from an external system

1. You need to have an email and a journey created in MC
2. You need to authenticate first and obtain the Access Token (valid for 20min, so it should be reused)
3. Use the Token and the Transactional API or the Fire Event API endpoint (based on your needs) to trigger an email send.

There are a lot of things that should be taken into consideration aside from what is written here, but the best idea would be to work with your MC Team and have them guide and support you in this implementation.