To issue an asynchronous API request, include the Options object in the request. This table shows the properties of the Options object.
| Name | Type | Description |
|---|---|---|
RequestType | String | Required. The processing type for the request. To enable asynchronous processing, set the value of this property to Asynchronous. |
SendResponseTo | SendResponseTo object | Required. An object that determines the type, format, and other characteristics of responses. |
CallsInConversation | Integer | The number of requests in the conversation. This value must be the same for all requests within a specific conversation. |
ConversationID | String | A unique string that is used to identify and coordinate conversations and result processing. If the request includes the CallsInConversation or SequenceCode properties, this field is required. |
CorrelationID | String | An identifier that is returned in the async response. |
QueuePriority | String | The triggered send priority. There are three possible values:
Medium. |
RequestExpirationTime | String | The date and time when the asynchronous API request expires. Specify the value in ISO 8601 format with UTC time or a timezone offset. When you specify both RequestExpirationTime and ScheduledTime in a request, the RequestExpirationTime must occur after the ScheduledTime. |
ScheduledTime | String | The date and time at which the request must be processed. Specify the value in ISO 8601 format with UTC time or a timezone offset. The specified time can be up to 30 days in the future. |
SequenceCode | Integer | The order of this request in a multi-part conversation. SequenceCode must start at 1 and continue in sequence. You can send the parts of the conversation in any order, but the system processes the conversation parts in order based on the value of this property. |
When asynchronous triggered send processing is enabled, the system validates the required fields and email addresses before adding the request to the queue. If your request is invalid, this validation step provides immediate feedback.
The SendResponseTo object determines how responses are handled for asynchronous requests.
| Name | Type | Description |
|---|---|---|
ResponseType | String | Required. The type of response that the system returns. There are three possible values:
|
RespondWhen | String | Required. The conditions that cause the system to send a response. There are six possible values:
|
IncludeResults | Boolean | To return XML-serialized Result objects, specify true. If the ResponseType is Email, the system sends this information as an attachment to the email message. |
IncludeObjects | Boolean | To populate the Object property with the result XML, specify true. |
OnlyIncludeBase | Boolean | To populate the Object property with the entire object, specify true. To populate it with the APIObject properties, specify false. If the value of IncludeObjects in the request is false, the system ignores this property. |
ResponseAddress | String | Required. The address to send the response to. If the value of ResponseType is Email, this value must be an email address. If ResponseType is HTTPPost, this value must be an HTTPS callback URL. |
Use the ConversationID property to group API requests that are part of a conversation. Calls that include the same conversation ID are processed in order based on the value of the SequenceCode property in each request. A ConversationID must be unique, but it can match the ID of another data type in your account. Use the matching IDs to associate the ConversationID activity with other data in reports.
The system starts processing a conversation after you submit all of the parts of the conversation. The value of the CallsInConversation property determines the number of parts in a conversation. If your request doesn’t include the SequenceCode and CallInConversation properties, the system assumes that the conversation has only one part and begins processing immediately. If there’s a delay of more than 5 minutes between the submission of conversation parts, the entire conversation fails.
If a conversation fails during processing, the system doesn’t process subsequent requests in the conversation. If the processing of a conversation fails in the middle of a sequence, use the values of ConversationID and SequenceCode in the response to determine which requests didn’t complete. Next, submit the remaining conversation parts with a new conversation ID.
The CorrelationID identifies the individual top-level objects in a request. Use this ID to report on individual top-level objects in a call, as opposed to retrieving results for the entire request.
You don’t need to specify ConversationID when you specify a CorrelationID. Each object in a request must have a unique CorrelationID, but separate requests can have the same CorrelationId. If you don’t specify a value for ConversationID, you can use the RequestID to retrieve the results of the request.
When you pass multiple objects in an asynchronous request, the CorrelationID replaces the array index. The CorrelationID allows reporting on individual top-level objects in a call.
You can retrieve the CorrelationID in three ways.
ResultItems for the request
j