Work with SOAP API

The SOAP API provides comprehensive integration flexibility by exposing Marketing Cloud Engagement features as interoperable, reusable services. The API is built on web service standards that assure high levels of security and reliability. Because it’s SOAP-based, developers can use leading integration processes and tools. The API is designed to:

Enable businesses to innovate their email strategy.
Provide alternative approaches to typical integration pain points. For example, you can manage your subscribers externally.
Enable behavioral data to be programmatically created and acted upon.

When working with SOAP API, you can only successfully complete calls that use features enabled for the account containing your API user login. If a feature hasn’t been enabled for your account, you can’t use SOAP API to perform that feature. Contact your Account Executive for more information about identifying and enabling features for your account.

Create Email

The SOAP API supports many different email creation scenarios. You can create emails in the web interface and operate on the emails with the API or perform the entire email creation process with the API.

Retrieve Tracking Data

With SOAP API, you can retrieve tracking data and use it to create reports and dashboards to see how your customers view and respond to your data. You can filter tracking data based on actual data returned by SOAP API. Dates returned in these tracking events represent the date on which the event occurred. By default, our system operates on CST (UTC-6:00). You can specify time ranges using different offsets.

In most production implementations, data volume in the account requires you to include specific JobIDs in the filter criteria of the request. If requests that don’t specify a JobID time out during processing, add a JobID in the filter. If it isn’t possible to specify a JobID, or if your implementation requires a broad range of JobIDs, use a data extract-based procedure instead.

Dates returned in these tracking events represent the date on which the event occurred. By default, our system operates on CST (UTC-6:00). You can specify time ranges using different offsets using the XSD DateTime standard. For example, the following value specifies 10:00 AM January 1, 2018 using EDT time: 2018-01-01T10:00:00-04:00

When retrieving OpenEvents and filtering on the OpenDate using a date range, you receive all events that occurred within the specified date range. These events include events from messages where the send occurred outside of the specified data range.

The SOAP API returns up to 2500 records at a time and indicates whether more data is available. You can perform more retrieves to access this data or continue where the prior identical retrieve request left off:

Send Email

You can schedule and send emails with SOAP API. You can identify message recipients using dynamic, rule-based segmentation of lists, events, and profiles. After the send, you can use the API to return aggregate statistics.

The scope of SOAP API doesn’t include functions related to configuring your account. For example, functions for configuring private IP addresses, dedicated domains, and file transfer locations aren’t included. The API also offers little control over the creation and execution of file transfer activities, groups, and data filters.

Asynchronous Processing

Your account can be configured to queue calls and process them asynchronously, rather than processing each call at the time it’s made. Asynchronous processing prevents dropping calls that are made when the service is unavailable.

If you use asynchronous processing for your triggered emails, you can also set the priority of the email send. For more information about this feature, contact your Account Executive.

Expected Response Times for Typical Synchronous Calls

Response times for calls vary depending on the types of calls and the amount of data handled by that call. These values represent expected and approximate times and aren’t guarantees.

Call Type	Expected Response Time in Seconds
Triggered Sends	3
Single Subscriber Add	3
Single Email Send	3
Tracking Data Retrievals	30

Deliverability

When planning your integration, consider the following deliverability issues. If you have questions, contact your Account Executive.

Opt-in

Lists that you bring in to Marketing Cloud Engagement must contain subscribers who have opted-in.

Marketing Email Laws

Marketing emails must comply with applicable email marketing laws in each subscriber’s country. If you have questions about whether an email is a marketing or transactional message, contact Salesforce Customer Support or your account executive.

Deliverability Reports

Deliverability reports for an account or subaccounts are sent to the email address associated with the main SOAP API account.

Private Domain and Private IP Address

SOAP API accounts must have a private domain and private IP address to protect your integration from potential abuse from other SOAP API enabled accounts.

From Address

Use dedicated email domains, as opposed to free email providers such as Hotmail, Yahoo, and Gmail. Using a free email provider email address can decrease the deliverability of your customers’ email messages.

Error Handling

The SOAP API commands can act on multiple objects in a single call. Layers of error handling support the flexibility offered by the API.

Command Level

Each command returns a single string that represents the overall status of the action. This status can help you understand errors that occur while the request is being processed.

1String status =
2integrationFramework.Execute(ref requestID, new ExecuteRequest[] { request }, out results);
3// Command Level Status:
4// status = OK, Has Error, or Error

Command-Level Status Values

OK - This status code states that all objects were successfully acted upon.
Has Error- Valid for Create or Update calls with multiple APIObject objects-this status code states that some of the operations failed, while others succeeded.
Error - This status code states that all delete operations failed during validation or processing.

Object Level

1CreateResult[] results =
2integrationFramework.Create(new CreateOptions(), subscribers, out requestid, out status);
3// Print out results for each new object created
4foreach (CreateResult result in results) {
5Console.WriteLine(string.Format("Results for object {0}: Status code: {1}.  Message: {2}.", result.OrdinalID, result.StatusCode, result.StatusMessage));
6}

Output

Results for object 0: Status code: OK. Message: Created Subscriber.

Each command also returns a collection of result objects. Each result object contains both an overall status and a status message. The status message contains details about the overall status. Object-Level status values:

OK - This status code states that the object was successfully acted upon.
Error - This status code states that the object was unsuccessfully acted upon.

Internationalization

The SOAP API allows emails to be sent in a variety of character sets. However, this broad support doesn’t guarantee that content is correctly displayed across all email clients. Test international emails extensively.

Supported Encoding for Outbound Emails

The default encoding for outbound email is us-ascii. The default can be overridden with any of the following encoding types:

Character Set	Encoding Type
Central European	iso-8859-2
Chinese	big5
Japanese	Shift-JIS
Japanese	iso-2022-JP
Korean	EUC-KR
Russian	koi8-r
Unicode	UTF-8
United States	us-ascii
Western European	iso-8859-1

The character set of an email can be overridden when the Email object is created or when the email is associated with a Send object. This code example shows how to specify the character set when creating an Email object.

1Email email = new Email();
2email.CharacterSet = "UTF-8";
3Send send = new Send();
4send.Email...
5// other email information
6send.Email.CharacterSet = "UTF-8";

Email Creation and Internationalization

Marketing Cloud Engagement supports Unicode text in the email subject line, HTML body, and text body. Unicode is also supported for attribute values if Marketing Cloud Engagement doesn’t serve as a database of record.

Triggered Emails and Internationalization

It’s possible to create different TriggeredSendDefinitions for each language, complete with different email content types and headers and footers. For example, if Chinese support is required in an application, you can programmatically reference the associated TriggeredSendDefinitions. The benefits of this approach include a single account for all content types and response metrics that are broken out by language.

Null Values

Depending on the development platform used in your integration and the WSDL proxy used, a generated object can have additional properties for handling null values. The following code samples are examples from .NET 2.0 (for the development environment) and WSE 3.0 (the proxy generator). Due to the way .NET (and other platforms such as Java) handles value types with a null value, the proxy generator outputs more properties to provide the null value granularity assumed by the WSDL.

Retrieving Objects and Subobjects

Some WSDL objects include subobjects with individual properties. In order to retrieve the information for those subobjects, you must specify those properties on the subobject in your call. For example, the Send object includes Client and Email subobjects, and you can specify the ID of those subobjects in order to retrieve that information. To get information about those subobjects, perform a retrieve on the Send object and include the Send.Client.ID and Send.Email.ID properties in that call. After you retrieve the information, use the IDs to perform a second retrieve and get more information about those subobjects.

Not all properties on all subobjects are available to be retrieved. In general, you can perform retrieves using ID, ObjectID, and CustomerKey.

Working with Dates

Marketing Cloud Engagement stores dates in Central Standard Time (CST) with no variation for Daylight Savings Time. When setting dates on objects, use a Coordinated Universal Time (UTC) offset for best results (UTC-6:00). When retrieving dates, convert the dates to the UTC offset to ensure that they’re in a format that’s suitable for your application.

Managing Downtime

When building an integration with an external SOA service, it’s useful to have a queuing mechanism in place as part of your architecture to handle downtime events. Marketing Cloud Engagement provides an asynchronous architecture that can receive calls regardless of system status to handle issues related to its systems. For Internet-related issues, having appropriate queues in place helps when delivering mission-critical emails.

Effective use of the GetSystemStatus call can allow an application to gracefully handle downtime. This example shows how to use the GetSystemStatus call.

Don’t run this call before every API call. Only run it when an error or exception occurs.

Note

1// 1. Invoke the GetSystemStatus Call
2string message;
3SystemStatusResult[] results =
4integrationFramework.GetSystemStatus(null, out status, out message, out requestID);
5// 2. Output the Overall Status of the Request
6Console.WriteLine("Status: {0}", status);
7// 3. Output the Status of the System
8foreach (SystemStatusResult result in results)
9{
10   Console.WriteLine("_________________");
11   Console.WriteLine(result.SystemStatus);
12  }