Sending an Email with Dynamic Content from Marketo using the API

Imagine you want to automate your call center follow-up emails. After your support rep speaks with a customer, you would like to automatically send an email thanking them for contacting your company. Let’s take this a step further, and say you want to include the specific conversation topic discussed with the customer that you track in your CRM. You can do this from Marketo using the requestCampaign SOAP API to send an email with dynamic content.

The requestCampaign API allows you to pass in a lead or leads. It also allows you to pass in Program Tokens that can be used with an existing Campaign to send dynamic content. The requestCampaign SOAP API requires the email recipient to exist in Marketo. So before calling the requestCampaign API, use the getLead API to verify if the email exists in Marketo.

We’ll show you first how to create a Smart Campaign, second how to set up a trigger to send a campaign via the API, third how to create an email that accepts dynamic content via Program Tokens, fourth how to define an email as part of a flow action, and fifth a code sample that would be used to execute this campaign.

How to Create a New Smart Campaign in Marketo

Smart Campaigns in Marketo execute all of your marketing activities. You can set up a series of automated actions to take on a smart list of contacts. In the case of sending transactional emails, you set up a trigger in the campaign, as shown below, to send emails using the API. First let’s set up the Smart Campaign.

1. In Marketing Activities, choose a Program and then under the New dropdown, click on New Local Asset

2. Click on Smart Campaign

3. Enter smart campaign name and click Create

Add Triggers to a Smart Campaign

Adding Triggers to a Smart Campaign allows you to make a Smart Campaign run on one person at a time based on a live event, which in this case is a request via the requestCampaign API.

1. Search for the “Campaign is Requested” trigger and then drag and drop it to the canvas.

2. In the trigger, select “is” and “Web Service API.”

How to Pass in Dynamic Content Using the API

In Marketo, My Tokens are variables that you can use in your Program. My Tokens enable you to enter information pertaining to your Program in one place, replace that information with a value you specify, and retrieve this information in other parts of the application, such as an email template.

Using the requestCampaign SOAP API, you can pass an array of Program Tokens, which will override existing tokens. After the campaign runs, the tokens are discarded.

You create My Tokens at either the Campaign folder level, or at the Program level. My Tokens at the Campaign folder level will inherit down to all Programs contained within the Campaign folder. If you create My Tokens at the Campaign folder level, you can overwrite the inherited value at the Program level. For example, if you define tokens for the Program Date and the Program Description at the Campaign folder level, you can overwrite these values at the individual Program level. Here’s how to do this.

1. From the Marketing Activities tree, select the Campaign folder or Program where you want to create the tokens. From the top menu bar, select My Tokens. Then the My Tokens canvas will display. From the right hand side tree, drag a Token Type to the canvas, which in this case is “Text.” In the Token Name field, highlight My Token and enter a unique Token Name, which in this case is “my.conversationtopic.” In the Value field, enter a relevant Value for the token, which in this case is “Thank you for calling us today.” Note by using the API we will override the default My Token value. Click “Save” to save the custom token.

2. Create a New Email by clicking New. Then click on New Local Assets and select Email. Next fill out the relevant fields to name your email. When drafting your email, click the Token icon to include tokens in your email. Now that you have created your template email with Tokens, we will add the email as a flow action for the Campaign in the subsequent step. So when you call the campaign via the API, the email will be sent out.

How to Create Email Flow Action on a Campaign

The association of an email with a Smart Campaign allows marketers to manage how they want an email to look, and allows the third-party application to determine who receives it and when.

After creating an email as a new Local Asset, you can set it as a flow action in a campaign.

Find and select the email you want to send.

Code Sample to Call the requestCampaign API

After setting up the campaign and triggers in the Marketo interface, we will show you how to use the API to send an email. The first sample is a XML request, the second is a XML response, and the final one is a Java code sample that can be used to generate the XML request. We also show you how to find the campaign ID that is used when making a call to the requestCampaign API.

The API call also requires you to know the ID of the Marketo campaign beforehand. You can determine the campaign ID using either of the following methods:

1. Use the getCampaignsForSource API

2. Open the Marketo campaign in a browser and look at the URL address bar. The campaign ID (represented as a 4-digit integer) can be found immediately following “SC”. For example, https://app-stage.marketo.com/#SC1025A1. The bolded portion is the campaign ID – “1025.”

SOAP Request for requestCampaign

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.marketo.com/mktows/">
  <SOAP-ENV:Header>
    <ns1:AuthenticationHeader>
      <mktowsUserId>demo17_1_809939944BFABAE58E5D27</mktowsUserId><requestSignature>48397ad47b71a1439f13a51eea3137df46441979</requestSignature><requestTimestamp>2013-08-01T12:31:14-07:00</requestTimestamp>
    </ns1:AuthenticationHeader>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns1:paramsRequestCampaign>
      <source>MKTOWS</source>
      <campaignId>4496</campaignId>
      <leadList>
        <leadKey>
          <keyType>EMAIL</keyType>
          <keyValue>lead@company.com</keyValue>
        </leadKey>
      </leadList>
      <programTokenList>
        <attrib>
          <name>{{my.conversationtopic}}</name>
          <value>Thank you for calling about adding a line of service to your current plan.</value>
        </attrib>
      </programTokenList>
    </ns1:paramsRequestCampaign>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.marketo.com/mktows/">

<SOAP-ENV:Header>

<ns1:AuthenticationHeader>

<mktowsUserId>demo17_1_809939944BFABAE58E5D27</mktowsUserId><requestSignature>48397ad47b71a1439f13a51eea3137df46441979</requestSignature><requestTimestamp>2013-08-01T12:31:14-07:00</requestTimestamp>

</ns1:AuthenticationHeader>

</SOAP-ENV:Header>

<SOAP-ENV:Body>

<ns1:paramsRequestCampaign>

<source>MKTOWS</source>

<keyType>EMAIL</keyType>

<keyValue>lead@company.com</keyValue>

</leadKey>

</leadList>

<name>{{my.conversationtopic}}</name>

<value>Thank you for calling about adding a line of service to your current plan.</value>

</attrib>

</programTokenList>

</ns1:paramsRequestCampaign>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

SOAP Response for requestCampaign

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.marketo.com/mktows/">
  <SOAP-ENV:Body>
    <ns1:successRequestCampaign>
      <result>
        <success>true</success>
      </result>
    </ns1:successRequestCampaign>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.marketo.com/mktows/">

<SOAP-ENV:Body>

<ns1:successRequestCampaign>

</result>

</ns1:successRequestCampaign>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

See below a sample Java program that executes the scenario described above.

import com.marketo.mktows.*;
import java.net.URL;
import javax.xml.namespace.QName;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBElement;
import javax.xml.bind.Marshaller;
 
 
public class RequestCampaign {
 
    public static void main(String[] args) {
        System.out.println("Executing Request Campaign");
        try {
            URL marketoSoapEndPoint = new URL("CHANGE ME" + "?WSDL");
            String marketoUserId = "CHANGE ME";
            String marketoSecretKey = "CHANGE ME";
             
            QName serviceName = new QName("http://www.marketo.com/mktows/", "MktMktowsApiService");
            MktMktowsApiService service = new MktMktowsApiService(marketoSoapEndPoint, serviceName);
            MktowsPort port = service.getMktowsApiSoapPort();
             
            // Create Signature
            DateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ");
            String text = df.format(new Date());
            String requestTimestamp = text.substring(0, 22) + ":" + text.substring(22);           
            String encryptString = requestTimestamp + marketoUserId ;
             
            SecretKeySpec secretKey = new SecretKeySpec(marketoSecretKey.getBytes(), "HmacSHA1");
            Mac mac = Mac.getInstance("HmacSHA1");
            mac.init(secretKey);
            byte[] rawHmac = mac.doFinal(encryptString.getBytes());
            char[] hexChars = Hex.encodeHex(rawHmac);
            String signature = new String(hexChars); 
             
            // Set Authentication Header
            AuthenticationHeader header = new AuthenticationHeader();
            header.setMktowsUserId(marketoUserId);
            header.setRequestTimestamp(requestTimestamp);
            header.setRequestSignature(signature);
             
            // Create Request
            ParamsRequestCampaign request = new ParamsRequestCampaign();
             
            request.setSource(ReqCampSourceType.MKTOWS);
             
            ObjectFactory objectFactory = new ObjectFactory();
            JAXBElement<Integer> campaignId = objectFactory.createParamsRequestCampaignCampaignId(4496);
            request.setCampaignId(campaignId);
             
            ArrayOfLeadKey leadKeyList = new ArrayOfLeadKey();
            LeadKey key = new LeadKey();
            key.setKeyType(LeadKeyRef.EMAIL);
            key.setKeyValue("lead@company.com");
             
            leadKeyList.getLeadKeies().add(key);
             
            JAXBElement<ArrayOfLeadKey> arrayOfLeadKey = objectFactory.createParamsRequestCampaignLeadList(leadKeyList);
            request.setLeadList(arrayOfLeadKey);

            ArrayOfAttrib aoa = new ArrayOfAttrib();
             
            Attrib attrib = new Attrib();
            attrib.setName("{{my.conversationtopic}}");
            attrib.setValue("Thank you for calling about adding a line of service to your current plan.");
             
            aoa.getAttribs().add(attrib);
             
            JAXBElement<ArrayOfAttrib> arrayOfAttrib = objectFactory.createParamsRequestCampaignProgramTokenList(aoa);
            request.setProgramTokenList(arrayOfAttrib);
 
            SuccessRequestCampaign result = port.requestCampaign(request, header);
 
            JAXBContext context = JAXBContext.newInstance(SuccessRequestCampaign.class);
            Marshaller m = context.createMarshaller();
            m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
            m.marshal(result, System.out);
             
        }
        catch(Exception e) {
            e.printStackTrace();
        }
    }
}

import com.marketo.mktows.*;

import java.net.URL;

import javax.xml.namespace.QName;

import java.text.DateFormat;

import java.text.SimpleDateFormat;

import java.util.Date;

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Hex;

import javax.xml.bind.JAXBContext;

import javax.xml.bind.JAXBElement;

import javax.xml.bind.Marshaller;

public class RequestCampaign {

public static void main(String[] args) {

System.out.println("Executing Request Campaign");

try {

URL marketoSoapEndPoint = new URL("CHANGE ME" + "?WSDL");

String marketoUserId = "CHANGE ME";

String marketoSecretKey = "CHANGE ME";

QName serviceName = new QName("http://www.marketo.com/mktows/", "MktMktowsApiService");

MktMktowsApiService service = new MktMktowsApiService(marketoSoapEndPoint, serviceName);

MktowsPort port = service.getMktowsApiSoapPort();

// Create Signature

DateFormat df = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ");

String text = df.format(new Date());

String requestTimestamp = text.substring(0, 22) + ":" + text.substring(22);

String encryptString = requestTimestamp + marketoUserId ;

SecretKeySpec secretKey = new SecretKeySpec(marketoSecretKey.getBytes(), "HmacSHA1");

Mac mac = Mac.getInstance("HmacSHA1");

mac.init(secretKey);

byte[] rawHmac = mac.doFinal(encryptString.getBytes());

char[] hexChars = Hex.encodeHex(rawHmac);

String signature = new String(hexChars);

// Set Authentication Header

AuthenticationHeader header = new AuthenticationHeader();

header.setMktowsUserId(marketoUserId);

header.setRequestTimestamp(requestTimestamp);

header.setRequestSignature(signature);

// Create Request

ParamsRequestCampaign request = new ParamsRequestCampaign();

request.setSource(ReqCampSourceType.MKTOWS);

ObjectFactory objectFactory = new ObjectFactory();

JAXBElement<Integer> campaignId = objectFactory.createParamsRequestCampaignCampaignId(4496);

request.setCampaignId(campaignId);

ArrayOfLeadKey leadKeyList = new ArrayOfLeadKey();

LeadKey key = new LeadKey();

key.setKeyType(LeadKeyRef.EMAIL);

key.setKeyValue("lead@company.com");

leadKeyList.getLeadKeies().add(key);

JAXBElement<ArrayOfLeadKey> arrayOfLeadKey = objectFactory.createParamsRequestCampaignLeadList(leadKeyList);

request.setLeadList(arrayOfLeadKey);

ArrayOfAttrib aoa = new ArrayOfAttrib();

Attrib attrib = new Attrib();

attrib.setName("{{my.conversationtopic}}");

attrib.setValue("Thank you for calling about adding a line of service to your current plan.");

aoa.getAttribs().add(attrib);

JAXBElement<ArrayOfAttrib> arrayOfAttrib = objectFactory.createParamsRequestCampaignProgramTokenList(aoa);

request.setProgramTokenList(arrayOfAttrib);

SuccessRequestCampaign result = port.requestCampaign(request, header);

JAXBContext context = JAXBContext.newInstance(SuccessRequestCampaign.class);

Marshaller m = context.createMarshaller();

m.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);

m.marshal(result, System.out);

}

catch(Exception e) {

e.printStackTrace();

}

After you make a call via the requestCampaign API, you can confirm it by checking to see if the Smart Campaign has run in Marketo.

* This article contains code used to implement custom integrations. Due to its customized nature, The Marketo Technical Support team is unable to troubleshoot custom work. Please do not attempt to implement the following code sample without appropriate technical experience, or access to an experienced developer.

Latest Blog Posts