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.

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 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:

• More Retrieves in Sent Events
• Retrieve All Records Since Last Batch

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.

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.

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.

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

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.

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

• 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 doesn’t guarantee that content is correctly displayed across all 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:

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.

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.

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.

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.

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

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.

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.

• Simple Object Access Protocol (SOAP)
• Web Service Description Language (WSDL)
• WS-I Basic Profile
• WS-Security 1.3

• Data Extracts
• Data Extracts Initiated with the SOAP API
• Triggered Email Scenario Guide for Developers
• Asynchronous Processing
• GetSystemStatus Method