Use SOAP API in Email Studio

Learning Objectives

After completing this unit, you’ll be able to:

• Work with the methods, objects, and endpoints of the SOAP API.
• Configure a basic email message in Marketing Cloud Engagement.
• Know when to use synchronous and asynchronous processing.

When Should You Use the SOAP API?

While the REST API applies to many Marketing Cloud Engagement apps, the SOAP API focuses specifically on integrating with Email Studio. Which means you can create, send, and retrieve tracking information on email messages—all using the SOAP API. Plus, this API also permits changes to account information.

Read on for more about working with Email Studio and legacy integrations in Marketing Cloud Engagement.

SOAP API Basics

The SOAP API authenticates using OAuth access tokens. Remember this from earlier? FYI, you can also authenticate with a UsernameToken created with a Marketing Cloud Engagement username and password, but the OAuth token provides a more secure connection.

The SOAP API also uses tenant-specific endpoints for both the WSDL and the endpoint. You can use these links to work with the provided methods and objects. Marketing Cloud Engagement also provides legacy endpoints if you’re working on existing implementations, but it’s best to use the new endpoints for any new development.

Methods and Objects

Marketing Cloud Engagement provides several different methods you can use in your requests. Your requests use these methods on different objects, such as Account, Email, Owner, and more. You can refer to the WSDL file or Salesforce Developers for a full list of available objects and properties. Spoiler alert: There’s a bunch! Here are just a few.

Some objects or associated sub-objects are for internal use only or reserved for future use.

Working with the SOAP API

When you work with the SOAP API, it’s helpful to keep a few things in mind.

• You can expect synchronous processing of your requests anywhere from 3 seconds (for a single email send) to 30 seconds (for retrieval of tracking data).
• Each request returns one of three statuses.
  • OK
  • Has Error
  • Error
• Marketing Cloud Engagement stores data values in central standard time (CST) with no variation for daylight saving time. You can use a coordinated universal time (UTC) offset when retrieving date information to make sure that information is optimized for your system.
• You can set different character sets for email messages depending on the culture codes you send to, so it’s a good idea to test these messages to make sure all characters appear correctly.

Example: Create an Email Message

Let’s take a look at some common SOAP API tasks. This C# example shows how to create a simple email. The code assigns a subject line and content, and an identifying name and location, so you can easily find it in your Marketing Cloud Engagement account.

Email email = new Email();
email.Subject = "Check out my way cool email";
email.Name = "Dynamic Email_" + DateTime.Now.ToShortTimeString();
email.HTMLBody = "<center>##Way Cool Email</center>";
email.TextBody = "Way Cool Email";
email.CharacterSet = "iso-8859-1";
email.CategoryID = 556442;  //This is the Folder where the email is stored.
email.CategoryIDSpecified = true;
CreateResult[] results = proxy.Create(new CreateOptions(), new APIObject[] { email }, out requestID, out status);

This next C# example shows one way to send an email message with an email send definition. That send definition includes the information you need to identify the email sent and any additional send details.

// 1. Create the EmailSendDefinition
EmailSendDefinition sd = new EmailSendDefinition();
sd.CustomerKey = "95";
// 2. Start the Send
PerformResult[] results = integrationFramework.Perform(new PerformOptions(), "start", new InteractionBaseObject[] { sd }, out status, out message, out requestID);
// 3. Print out overall results
System.Text.StringBuilder sb = new System.Text.StringBuilder();
sb.Append("Perform Send Definition");
sb.AppendFormat("\nOverall result: {0}.  RequestID: {1}, {2}\n{3}\n{4}\n{5}\nTaskID: {6}", status, requestID, message, results[0].ErrorCode, results[0].StatusCode, results[0].StatusMessage, results[0].Task.ID);
Console.WriteLine(sb.ToString());

After the send completes, you can retrieve tracking information on the send using this sample code. (Just remember, you need to include the JobID returned after the original send.)

/**
*Returns details of send - when you send email, it returns JobID.
*Use returned ID to get details.
*/
        public void testSendDetails()
        {
             RetrieveRequest retrieveRequest = new RetrieveRequest();
             retrieveRequest.ObjectType = "Send";
             String[] props = { "SentDate", "UniqueOpens", "NumberSent", "NumberDelivered", "HardBounces", "SoftBounces" };
retrieveRequest.Properties =props;
             /**
              * Use date range to get all sends that happened in range
          */
             /**
             SimpleFilterPart filter = new SimpleFilterPart();
             filter.Property = "SendDate";
             filter.SimpleOperator = SimpleOperators.greaterThanOrEqual;
             filter.DateValue = new DateTime[1];
             filter.DateValue[0] = DateTime.Now;
             retrieveRequest.Filter = filter;
             */
             /**
              * Details for the particular job
              */
              SimpleFilterPart filter = new SimpleFilterPart();
              filter.Property = "ID";
              filter.SimpleOperator = SimpleOperators.equals;
              filter.Value= new string[] {"12043295"};
              retrieveRequest.Filter = filter;
              /**
              * If this job happened from Child Account include ClientId in request.
              */
              /*
              ClientID id = new ClientID();
              id.ID = 90554;
              id.IDSpecified = true;
              retrieveRequest.ClientIDs = new ClientID[] {id};
              */
              APIObject[] results = null;
              String requestId = null;
              String response = soapClient.Retrieve(retrieveRequest, out requestId, out results);
              Send send = null;
              if (response != null && response.ToLower().Equals("ok"))
              {
                   if (results != null)
                   {
                      send = (Send) results[0];
                   }
              }
              Assert.IsNotNull(send);
           }

Most API objects return results in batches of 2,500. You can ask for smaller batches in your requests, or you can perform additional requests to retrieve results with more than 2,500 records.

Synchronous and Asynchronous Processing

You can choose to perform your requests as synchronous or asynchronous operations. Synchronous requests achieve almost immediate results. The SOAP API queues asynchronous operations to ensure that your requests don’t get lost if the service becomes unavailable. Use asynchronous processing to ensure more resilient requests to the SOAP API. This method protects against dropped requests in case of a system outage and queues your requests for more predictable performance. We also recommend making only 20 or fewer synchronous API threads per request. Those requests should include references for up to 50 objects per synchronous call or 100 objects per asynchronous call.

Stick around—the next unit gives you expert tips and resources to make the most of your API integrations.

Resources

• Salesforce Developer: SOAP API
• Salesforce Developer: Get Started with the SOAP API