SOAP API Best Practices

Planning

Use the best practices below to plan for the eventualities that could be encountered with your use of the SOAP API.

• Use the fewest amount of steps possible when moving or updating data in your SOAP API calls.
• Use asynchronous processing whenever possible to ensure the best response to your calls.
• Plan and map out the data flow of your API calls in order to maximize the effectiveness of your API interactions.
• Make sure to account for future growth when implementing your API solution
• Avoid using the XML API in your planning, as this API is in a maintenance state and will not receive additional functionality in the future.
• Plan for peaks in traffic to your website or system and know what happens when you reach the upper limits of your system's capabilities.
• Queue API calls and pull off data from those calls at a defined rate.
• Perform any stress tests in the production support environment instead of the production environment.
• Include code in your calls that retrieves the results of your call (such as the information in the CreateResult object) and responds appropriately, such as notifying you when an error occurs or taking a specific action when a successful Create call finishes.

You can use multiple concurrent API sessions to increase overall throughput. However, note that a large number of sessions may result in diminishing returns. Test your API calls thoroughly to ensure that you are using the optimum number of concurrent API sessions.

Maintaining Service Level Agreements

ExactTarget agrees to maintain consistent levels of service through the use of service level agreements, or SLAs. You should observe the best practices below in order to ensure the performance outlined in your SLA:

• Avoid sending a completely rendered email in high-volume or triggered sends.
• Use dynamic content instead of starting a send definition, pausing it, changing the message, and restarting the send definition. This practice delivers inconsistent tracking information, no aggregate tracking data, and adds data rows to your tracking information.
• Avoid using high-volume triggered send calls using the synchronous SOAP API. Consider using asynchronous API calls to reduce server strain.
• Store message content in content areas instead of data extensions.
• Use send logging instead of send-time attributes where possible.
• Restrict the number of synchronous threads in your calls to 20 or fewer.
• Restrict your API requests to 50 objects per synchronous call or 100 objects per asynchronous call.

Monitoring Sends Through the SOAP API

The best way to monitor sends through the API is by polling the Send object on the following properties:

1. SendID (identifier for the send)
2. SentTime (time the send completed)
3. NumberSent (number of emails sent)

NumberSent will increment as the send is processing. Processing will be complete once SentTime has a value.

If you have programs enabled for your account, you can set up those programs in your account's user interface and begin the programs from the SOAP API. You can also modify the components of that program (such as import definitions and email send definitions) through the SOAP API to better define the information you would like to use in monitoring your sends. By automating these tasks, you can gain an understanding of how a send is progressing by which tasks are being executed.

Triggered Sends

Use the best practices outlined below to improve the performance of your triggered sends via the SOAP API.

This logic allows you take advantage of the instant notifications of the synchronous API and the solid reliability of the asynchronous API.

• Use data extensions with your triggered sends to store relevant subscriber information instead of subscriber lists.
• Refrain from using unlimited-length text columns in data extension used for triggered sends.
• Keep your triggered send batches to numbers smaller than 100 for asynchronous calls and less than 50 for synchronous calls.
• Keep your maximum payload per call at less than 5MB.
• Pass less than 10 attributes to avoid decreased performances.
• Retrieve information for an HTTPGet from your own site before the triggered send in order to prevent connectivity issues and problem-causing surges of traffic.
• Use applicable Owner information and send classifications to set the From name and email address for a triggered send instead of passing those values in at the time of the send.
• You can use the following workflow to take advantage of both the synchronous and asynchronous SOAP API and make sure your calls process effectively:
  • Send your initial API request via the synchronous API, allowing you to receive immediate feedback if either the subscriber or request has issues
  • Retry that call up to three (3) times to account for potential timeouts or connectivity issues
  • Send failed call via asynchronous AP

Retrieving Data from the Application

Use data extracts to retrieve information from the system whenever possible. Examples of data extract use can be found in the articles below:

• Extract Method
• Using Tracking Extracts

Connection Failures and Timeouts

You should configure your code to handle potential problems with connecting to the SOAP API. Use the best practices outlined below to help your system handle these connectivity issues:

• Use the CorrelationID property to make sure that the SOAP API can evaluate whether a call is a continuation of a series of API calls or a repeat call made due to connection failures.
• Make sure to set client-side timeouts in your calls. Use the following examples as models:
  • Asynchronous operations - 30 seconds
  • Synchronous operations (not including tracking retrieves) - 120 seconds
  • Synchronous operations retrieving large sets of data - 300 seconds
• Enable client-side logging of errors so you can evaluate the reasons behind the failure of a call, even if connectivity to the SOAP API remains problematic.

Security

When interacting with the web service API, you should observe these best practices in order to maintain a secure connection between your integration or development environment and the ExactTarget system.

.NET

All optional, value-type properties of an object (such as the Int, bool, and enum types) have an additional Boolean property defined with Specified appended to the name.  This property is used to tell the XML Serializer whether the corresponding property should be included when generating the XML that will be sent.  When deserializing, this property indicates whether the corresponding property was included in the XML.  For example, the Subscriber object has an optional property called Status.  When the proxy class is generated, a "StatusSpecified" property will also be created.  When sending an object, if you specified a value for "Status", you must also set "StatusSpecified=true".  If you do not, the value of "Status" will not be serialized and sent to the server.  When receiving an object, you should check if "StatusSpecified=true".  If it is, then you know that a "Status" value was received and the data in the "Status" property is valid.  If "StatusSpecified=false", the value in "Status" will be the default value for that properties data type.

In the following table, if you use the code in the first column, the second column shows the XML that will be generated.  If you start with the XML in the second column, the third column shows what the properties will be set to.

To avoid confusion and possible bugs in your code, you should always be explicit as indicated in the first row.

When processing received objects, you should use the following pattern:

if (subscriber.StatusSpecified)
{
    Console.WriteLine(subscriber.Status);
}
else
{
    Console.WriteLine("The subscriber.Status property was not set");
}