Work with the 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 enterprise-level security and reliability. Because it is 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.

These examples illustrate some of the most common SOAP API uses.

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

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.

With the 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. Note that you can filter tracking data based on actual data returned via the 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 specifying a JobID is not possible, 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 1st 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:

You can schedule and send emails with the 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 SOAP API's scope does not include certain functions related to account configuration, such as configuring private IP addresses, dedicated domains, and file transfer locations. The API also offers little control over the creation and execution of file transfer activities, groups, and data filters.

PlatformLibrary / Module
.NETWSE 3.0, WCF
JavaAxis2, CXF, Glassfish
C++Axis2/C
PerlWSRF::Lite
PythonpyGridWare
PHPsoap-wsse.php, Axis2, Instantsvc
Rubywss4r

Your account can be configured to queue calls and process them asynchronously, rather than processing each call at the time it is 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. Contact your Account Executive to activate this feature.

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 are not guarantees.

Call TypeExpected Response Time in Seconds
Triggered Sends3
Single Subscriber Add3
Single Email Send3
Tracking Data Retrievals30

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

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

Marketing emails must comply with CAN-SPAM and other applicable email marketing laws. Transactional emails are less restricted by CAN-SPAM laws. If you have questions about whether an email is commercial or transactional, contact Salesforce Customer Support.

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

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.

As much as possible, require that your sub-accounts use From addresses that are not tied to free email providers like Hotmail, Yahoo, and Gmail. Using a free-email provider email address can decrease the deliverability of your customers' email messages (since Yahoo knows the email was not sent from Yahoo).

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

Each command returns single string representing the overall status of the action. This status can help you understand of any error occurring during the processing of the command. For example:

  • 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.

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.

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

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

Character SetEncoding Type
Central Europeaniso-8859-2
Chinesebig5
JapaneseShift-JIS
Japaneseiso-2022-JP
KoreanEUC-KR
Russiankoi8-r
UnicodeUTF-8
United Statesus-ascii
Western Europeaniso-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. For example:

Unicode is supported for the email subject line, HTML body, and text body. For example:

Unicode is also supported for attribute values if Marketing Cloud Engagement doesn't serve as database of record.

It is possible to create different TriggeredSendDefinitions for each language - complete with different email content types and headers and footers. For example, if an application needs to support Chinese and Unicode content types for transactional emails, you can programmatically reference the associated TriggeredSendDefinitions as follows:

The benefits of this approach include a single account for all content types and rollup reporting by language.

Depending on the development platform used in your integration and the WSDL proxy used, a generated object may have some more properties to handle 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. For example:

// Set a non-null value send.ID = 2345; send.IDSpecified = true;

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

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

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 dates are in the format suitable for your application.

When building an integration with an external SOA service, it is 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 prior to every API call. Only run it when an error or exception occurs.