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.

RequestTypeStringRequired. The processing type for the request. To enable asynchronous processing, set the value of this property to Asynchronous.
SendResponseToSendResponseTo objectRequired. An object that determines the type, format, and other characteristics of responses.
CallsInConversationIntegerThe number of requests in the conversation. This value must be the same for all requests within a specific conversation.
ConversationIDStringA 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.
CorrelationIDStringAn identifier that is returned in the async response.
QueuePriorityStringThe 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.
RequestExpirationTimeStringThe 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.
ScheduledTimeStringThe 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.
SequenceCodeIntegerThe 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.

ResponseTypeStringRequired. 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.
RespondWhenStringRequired. 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.
IncludeResultsBooleanTo return XML-serialized Result objects, specify true. If the ResponseType is Email, the system sends this information as an attachment to the email message.
IncludeObjectsBooleanTo populate the Object property with the result XML, specify true.
OnlyIncludeBaseBooleanTo 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.
ResponseAddressStringRequired. 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