Sending a transactional email from Marketo using the API

You can send a transactional email from Marketo using the requestCampaign SOAP API. It requires an existing Smart Campaign to be created using the Marketo UI. It also 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. 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.

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 define an email as part of a flow action, and fourth 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 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>
        <leadKey>
          <keyType>EMAIL</keyType>
          <keyValue>anotherlead@company.com</keyValue>
        </leadKey>
      </leadList>
    </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>

<keyType>EMAIL</keyType>

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

</leadKey>

</leadList>

</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");
             
            LeadKey key2 = new LeadKey();
            key2.setKeyType(LeadKeyRef.EMAIL);
            key2.setKeyValue("anotherlead@company.com");
             
            leadKeyList.getLeadKeies().add(key);
            leadKeyList.getLeadKeies().add(key2);
             
            JAXBElement<ArrayOfLeadKey> arrayOfLeadKey = objectFactory.createParamsRequestCampaignLeadList(leadKeyList);
            request.setLeadList(arrayOfLeadKey);
 
            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");

LeadKey key2 = new LeadKey();

key2.setKeyType(LeadKeyRef.EMAIL);

key2.setKeyValue("anotherlead@company.com");

leadKeyList.getLeadKeies().add(key);

leadKeyList.getLeadKeies().add(key2);

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

request.setLeadList(arrayOfLeadKey);

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();

}

* 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