Understand the Options Object in an Asynchronous Request

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: `High` — High priority requests are added to the queue immediately. The email is sent within 60 seconds. `Medium` — Medium priority requests are added to the queue every minute. The email is sent within 90 seconds. `Low` — Low priority requests are added to the queue every 5 minutes. The email is sent within 5 minutes. The default value is `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: `None` — Don’t send a response. You can use the Retrieve operation to get the response. `Email` — Send the response as an email. `HTTPPost` — Send the response as an HTTP POST request to a callback URL. Only HTTPS URLs are supported.
`RespondWhen`	String	Required. The conditions that cause the system to send a response. There are six possible values: `Always` — Send a response for all error and completion events. `Never` — Don’t send a response. `OnConversationComplete` — Send a response when the system finishes processing all parts of the conversation. `OnCallComplete` — Send a response when the system receives the request. `OnError` — Send a response when an error occurs. `OnConversationError` — Send a response when an error occurs within a conversation. `OnExpired` — Send a response when the date specified in the `RequestExpirationTime` property is exceeded.
`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.

By retrieving ResultItems for the request
From an asynchronous results data extract
From an email response that includes the result of the request

Options Base Object