Working with SOAP Web Service API

Prerequisites for Using the SOAP Web Service API

Perform the following steps before you begin to use the SOAP Web Service API:

• Create a user in your account with the API User property enabled. This property prevents passwords from expiring.
• Allow your development environment to access the WSDL file at:

  https://webservice.exacttarget.com/etframework.wsdl

  If your ExactTarget account uses the S4 instance, use this address:

  https://webservice.s4.exacttarget.com/etframework.wsdl

  If your ExactTarget account uses the S6 instance, use this address:

  https://webservice.s6.exacttarget.com/etframework.wsdl

  NOTE: Be sure to direct your development environment to the correct endpoint. Your API calls will not function if directed to the wrong endpoint.

• Configure your development environment to support WS-Security for authentication to the web service.

What is the SOAP Web Service API

The AMP SOAP Web Service API is a service-oriented architecture (SOA) for customers who need deeper integrations with their email service provider than the application interface can provide. The web service API provides comprehensive integration flexibility by exposing portions of functionality of the ExactTarget application as interoperable, reusable services. The composite processes and solutions combine with other services to meet your business needs.

The web service 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 web service 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.

Why Use the SOAP Web Service API

While you can accomplish several different tasks using the SOAP API, the examples below illustrate some of the most common SOAP API uses.

NOTE: 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 cannot use the SOAP API to perform that feature. Please contact your ExactTarget representative for more information about identifying and enabling features for your account.

Authentication

Authenticating to the AMP SOAP Web Service API requires passing a WS-Security 1.0 security token in the SOAP header.

Development Platform Support for WS-Security 1.0

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

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

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

Triggered Emails

See the Triggered Emails Scenario Guide for Developers for detailed information on implementing triggered emails with the Web Service API.

Internationalization

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

Email email = new Email(); 
email.CharacterSet = "UTF-8"; 
Send send = new Send(); 
send.Email... 
// other email information 
send.Email.CharacterSet = "UTF-8";

Email email = new Email();
email.Subject = "Unicode Supported";
email.HTMLBody = "Unicode Supported";
email.TextBody = "Unicode Supported";

String encoding = "big5";
TriggeredSendDefinition tsd = new TriggeredSendDefinition ();
tsd.CustomerKey = encoding + " Order Confirmation";

TriggeredSend ts = new TriggeredSend();
TriggeredSend.TriggeredSendDefinition = tsd;
... // additional triggered send information

Null Values

Depending on the development platform used in your integration and the WSDL proxy used, a generated object may have some additional 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 additional properties to provide the null value granularity assumed by the WSDL.

Example

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

Retrieving Objects and Sub-Objects

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.

Working with Dates

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

Managing Downtime

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 any downtime related to ExactTarget or your application. ExactTarget provides an asynchronous architecture that can receive calls regardless of system status to handle issues related to ExactTarget 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 any downtime related to ExactTarget, the internet, or your application. Below is an example of the GetSystemStatus call. Do not run this call prior to every web service call, but only on exception scenarios. For example, if you receive a SOAP fault or another unexpected error, run this call to ensure the exception was not the result of ExactTarget system maintenance.

// 1. Invoke the GetSystemStatus Call 
string message; 
SystemStatusResult[] results = 
    integrationFramework.GetSystemStatus(null, out status, out message, out requestID);  

// 2. Output the Overall Status of the Request
Console.WriteLine("Status: {0}", status);

// 3. Output the Status of the System
foreach (SystemStatusResult result in results)
{
       Console.WriteLine("_________________");
       Console.WriteLine(result.SystemStatus);
}

Supported Standards

The SOAP API supports the following standards:

• Simple Object Access Protocol (SOAP) - http://www.w3.org/TR/soap12-part1/
• Web Service Description Language (WSDL) - http://www.w3.org/TR/2001/NOTE-wsdl-20010315
• WS-I Basic Profile - http://www.ws-i.org/Profiles/BasicProfile-1.1.html
• WS-Security 1.3 - http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/os/ws-securitypolicy-1.3-spec-os.html