Sending Transactional Emails with the Marketo REST API: Part 1

July 17, 2015 | by

A common use case for the Marketo API is to trigger the sending of transactional emails to specific records via the Request Campaign API call.  You can find an example covering this use case with the SOAP API here.  There are a few configuration requirements within Marketo in order to execute the required call with the Marketo REST API.

  • The recipient must have a record within Marketo
  • There needs to be a Transactional Email created and approved in your Marketo instance.
  •  There needs to be an active trigger campaign with the Campaign is Requested, Source: Web Service API, that is set up to send the email

First create and approve your email.  If the email is truly transactional, you will likely need to set it to operational, but be sure that it legally qualifies as operational.  This is configured from with the Edit Screen under Email Actions > Email Settings:

Request Campaign - Email Settings

Request Campaign - Operational

Approve it and we’re ready to create our campaign:

RequestCampaign - Approve Draft

If you’re new to creating campaigns, check out the Create a New Smart Campaign article on docs.marketo.com.  Once you’ve created your campaign, we need to go through these steps.  Configure your Smart List with the Campaign is Requested trigger: Request Campaign - Smart List

Now we need to configure the flow to point a Send Email step to our email: Request Campaign - Flow

Before activation, you’ll need to decide on some settings in the Schedule tab.  If this particular email should only ever be sent once to a given record, then leave the qualification settings as is.  If it’s required that they receive the email multiple times, though, you’ll want to adjust this to either every time or to one of the available cadences: Qualification Rules

Now we’re ready to activate:

Request Campaign - Schedule

Sending the API Calls

Note: In the Java examples below, we’ll be using the minimal-json package to handle JSON representations in our code.  You can read more about this project here: https://github.com/ralfstx/minimal-json

The first part of sending a transactional email through the API is ensuring that a record with the corresponding email address exists in your Marketo instance and that we have access to its lead ID.  For the purposes of this post, we will assume that the email addresses are in Marketo already, and we only need to retrieve the ID of the record.  For this, we will be using the Get Multiple Leads by Filter Type call, and we will be reusing some of the Java code from the previous post on authenticating and retrieving lead data from Marketo. Let’s take a look at our Main method for to request the campaign:

To get to these results from the JsonObject response of leadsRequest, we’ll need to write some code .  To retrieve the first result in the Array, we need to extract the Array from the JsonObject and get the object indexed at 0:

From here now all we need to do is the Request Campaign call.  For this, the required parameters are ID in the URL of the request, and an array of JSON objects containing one member, “id.”  Let’s take a look at the code for this:

This class has one constructor taking an Auth, and the Id of the campaign.  Leads are added to the object either by passing an ArrayList<Integer> containing the Ids of the records to setLeads, or by using addLead, which takes one integer and appends it to the existing ArrayList in the leads property.  To trigger the API call to pass the lead records to the campaign, postData needs to be called, which returns a JsonObject containing the response data from the request.  When request campaign is called, every lead passed to the call will be processed by the target trigger campaign in Marketo and be sent the email which was created previously. Congratulations, you’ve triggered an email through the Marketo REST API.  Keep an eye out for Part 2 where we’ll look at dynamically customizing the content of an email through Request Campaign.

Read Part 2 here.