Response Options

All response options allow you to retrieve the raw XML body of the response. To process the XML in an object-oriented environment, deserialize it. Your web server must have the capacity to handle the expected call volume. Callbacks that fail aren’t retried.

HTTP Post Callback

Use the properties in this table to specify which callbacks to perform.

Name	Description
`RequestID`	The unique identifier of the request. This value is returned the first time the call is made.
`ConversationID`	The ConversationID that the request belongs to. If the request isn’t part of a conversation, this value is blank.
`OverallStatusCode`	The value that is returned in a synchronous call.
`StatusCode`	Contains the same content as `OverallStatusCode`.
`StatusMessage`	The value that is returned in the `Status` property in a synchronous call.
`ErrorCode`	The first error code in the result. If no errors were found, this value is blank.
`RequestType`	The type of request. Always returns `Asynchronous`.
`ResultType`	Contains the same content as `RequestType`.
`ResultDetailXML`	The XML serialized results.
`SequenceCode`	The `SequenceCode` that was specified in the request. If the request isn’t part of a conversation, this value is blank.
`SendResponseTo.RespondWhen`	Determines the types of events that cause the system to send an email with results. `OnCallComplete` — Send a notification when the request finishes processing, regardless of whether it finishes successfully or with errors. `OnConversationComplete` — Send a notification when the conversation finishes processing, regardless of whether the conversation finishes successfully or with errors. `OnError` — Send a notification when an error occurs in the request. `OnConversationError` — Send a notification when an error occurs in the conversation. `Never` — Don’t send notifications. The default value is `Never`.
`SendResponseTo.ResponseAddress`	The URL to send the callback to. HTTP Post callbacks require a public HTTPS URL.
`SendResponseTo.IncludeResults`	When `true`, the response includes XML serialized Result objects. When `false`, the HTTP POST is a basic notification. The default value is `false`.
`SendResponseTo.IncludeObjects`	When `true`, the `Object` property in the response is populated in the result XML. If the value of the `IncludeResults` property is `false`, this property is ignored.
`SendResponseTo.OnlyIncludeBase`	When `true`, the `Object` property in the response includes only the base API object. If the value of the `IncludeObjects` property is `false`, this property is ignored.

This C# code example performs an HTTP Post action to https://dev.example.com/partneremail. The results include the entire Object property.

Sample C# Request

1APIObject[] subscribers = new APIObject[1];
2Subscriber subscriber = new Subscriber();
3subscriber.EmailAddress = "john@example.com";
4subscriber.SubscriberKey = "23456789";
5/*
6 * Attribute selection:
7 * For best performance ensure the triggered send is using fields that exist on a data extension as attributes
8 *
9 * HTML__ is a prefix valuable when sending larger than 2000 characters through a legacy subscriber attribute
10 * The HTML__ prefix is not neccessary for data extension fields.
11 */
12subscriber.Attributes = new AsyncTestSuite.IntegrationFramework.Attribute[2];
13subscriber.Attributes[0] = new AsyncTestSuite.IntegrationFramework.Attribute();
14subscriber.Attributes[0].Name = "FirstName";
15subscriber.Attributes[0].Value = "John";
16subscriber.Attributes[1] = new AsyncTestSuite.IntegrationFramework.Attribute();
17subscriber.Attributes[1].Name = "YearOfBirth";
18subscriber.Attributes[1].Value = "1989";
19subscribers[0] = subscriber;
20CreateOptions co = new CreateOptions();
21co.RequestType = RequestType.Asynchronous;
22co.RequestTypeSpecified = true;
23co.SendResponseTo = new AsyncResponse[1];
24co.SendResponseTo[0] = new AsyncResponse();
25co.SendResponseTo[0].ConversationID = "firsttest";
26co.SendResponseTo[0].RespondWhen = RespondWhen.OnCallComplete;
27co.SendResponseTo[0].RespondWhenSpecified = true;
28co.SendResponseTo[0].ResponseType = AsyncResponseType.HTTPPost;
29co.SendResponseTo[0].ResponseAddress = "https://dev.example.com/partneremail";
30co.SendResponseTo[0].IncludeResults = true;
31co.SendResponseTo[0].IncludeResultsSpecified = true;
32co.SendResponseTo[0].IncludeObjects = true;
33co.SendResponseTo[0].IncludeObjectsSpecified = true;
34CreateResult[] results = integrationFramework.Create(co, subscribers, out requestID, out status);
35Console.WriteLine(results[0].StatusCode);
36Console.WriteLine(results[0].StatusMessage);
37Assert.IsNotNull(results);
38Assert.AreEqual("OK", status);

Sample C# Result

1// Publicly Available ASPX Web Page
2string requestID = Request.Form["RequestID"];
3string conversationID = Request.Form["ConversationID"];
4string overallStatusCode = Request.Form["OverallStatusCode"];
5string statusCode = Request.Form["StatusCode"];
6string statusMessage = Request.Form["StatusMessage"];
7// The error code associated with the first errored object (the one that stopped the conversation)
8string errorCode = Request.Form["ErrorCode"];
9string requestType = Request.Form["RequestType"];
10string resultType = Request.Form["ResultType"];
11// Optional and may be large
12string resultDetailXML = Request.Form["ResultDetailXML"];
13string sequenceCode = Request.Form["SequenceCode"];
14switch (overallStatusCode)
15{
16    case "OK":
17        // log the conversationID successful
18        break;
19
20    case "Has Error":
21        // Handle Errors
22        // Submit new conversation if needed
23        break;
24
25    case "Error":
26        // Handle Errors
27        // Submit new conversation if needed
28       break;
29}

1APIObject[] subscribers = new APIObject[1];
2Subscriber subscriber = new Subscriber();
3subscriber.EmailAddress = "john@example.com";
4subscriber.SubscriberKey = "23456789";
5/*
6 * Attribute selection:
7 * For best performance ensure the triggered send is using fields that exist on a data extension as attributes
8 *
9 * HTML__ is a prefix valuable when sending larger than 2000 characters through a legacy subscriber attribute
10 * The HTML__ prefix is not neccessary for data extension fields.
11 */
12subscriber.Attributes = new AsyncTestSuite.IntegrationFramework.Attribute[2];
13subscriber.Attributes[0] = new AsyncTestSuite.IntegrationFramework.Attribute();
14subscriber.Attributes[0].Name = "FirstName";
15subscriber.Attributes[0].Value = "John";
16subscriber.Attributes[1] = new AsyncTestSuite.IntegrationFramework.Attribute();
17subscriber.Attributes[1].Name = "YearOfBirth";
18subscriber.Attributes[1].Value = "1989";
19subscribers[0] = subscriber;
20CreateOptions co = new CreateOptions();
21co.RequestType = RequestType.Asynchronous;
22co.RequestTypeSpecified = true;
23co.SendResponseTo = new AsyncResponse[1];
24co.SendResponseTo[0] = new AsyncResponse();
25co.SendResponseTo[0].ConversationID = "firsttest";
26co.SendResponseTo[0].RespondWhen = RespondWhen.OnCallComplete;
27co.SendResponseTo[0].RespondWhenSpecified = true;
28co.SendResponseTo[0].ResponseType = AsyncResponseType.HTTPPost;
29co.SendResponseTo[0].ResponseAddress = "https://dev.example.com/partneremail";
30co.SendResponseTo[0].IncludeResults = true;
31co.SendResponseTo[0].IncludeResultsSpecified = true;
32co.SendResponseTo[0].IncludeObjects = true;
33co.SendResponseTo[0].IncludeObjectsSpecified = true;
34CreateResult[] results = integrationFramework.Create(co, subscribers, out requestID, out status);
35Console.WriteLine(results[0].StatusCode);
36Console.WriteLine(results[0].StatusMessage);
37Assert.IsNotNull(results);
38Assert.AreEqual("OK", status);

Retrieve

You can retrieve one ResultMessage object per request. To retrieve the full XML result, add the ResultDetailXML to the Properties collection. To optimize performance, include a filter so that data is only returned for specific requests.

This example retrieves data for a single request ID.

1RetrieveRequest rr = new RetrieveRequest();
2rr.ObjectType = "ResultMessage";
3rr.Properties = new string[] { "CreatedDate", "RequestID", "ConversationID", "CallsInConversation", "SequenceCode", "StatusCode", "ErrorCode", "StatusMessage" };
4SimpleFilterPart sfp = new SimpleFilterPart();
5sfp.Property = "RequestID";
6sfp.SimpleOperator = SimpleOperators.equals;
7sfp.Value = new string[] {"2519c614-6817-4e9e-a6e1-26b7d160c8b5"};
8
9rr.Filter = sfp;
10APIObject[] results;
11String status = integrationFramework.Retrieve(rr, out requestID, out results);
12// Will return a maximum of 2500 without paging support
13Console.WriteLine(String.Format("Number of Results:\t{0}", results.Length));
14Console.WriteLine("Result Details");
15Console.WriteLine("--------------------------");
16Console.WriteLine("CreatedDate\tRequestID\tConversationID\tCallsInConversation\tSequenceCode\tStatus\tErrorCode\tMessage");
17foreach (APIObject result in results)
18{
19    ResultMessage resultMsg = result as ResultMessage;
20    Console.WriteLine(String.Format("{0}\t{1}\t{2}\t{3}\t{4}\t{5}\t{6}\t{7}", resultMsg.CreatedDate, resultMsg.RequestID, resultMsg.ConversationID, resultMsg.CallsInConversation, resultMsg.SequenceCode, resultMsg.StatusCode, resultMsg.ErrorCode, resultMsg.StatusMessage));
21}

One ResultItem is available for every top-level object in the request. If a request creates 3 Subscriber objects, 3 ResultItem objects are available for the request.

Email

This call returns an email after processing of the request or conversation is complete. The email can include a ZIP file attachment named results.zip, which contains an XML file called results.xml.

Property	Data Type	Description
`RespondWhen`	String	Determines the types of events that cause the system to send an email with results. `OnCallComplete` — Send a notification when the request finishes processing, regardless of whether it finishes successfully or with errors. `OnConversationComplete` — Send a notification when the conversation finishes processing, regardless of whether the conversation finishes successfully or with errors. `OnError` — Send a notification when an error occurs in the request. `OnConversationError` — Send a notification when an error occurs in the conversation. `Never` — Don’t send notifications. The default value is `Never`.
`ResponseAddress`	String	The email address to send results to.
`IncludeResults`	Boolean	When `true`, result data is included as an attachment to the response email. If the value is `false`, the email is a basic notification. The default value is `false`.
`IncludeObjects`	Boolean	When `true`, object data is populated in each `Result` object.

This example sends an email to responses@example.com with an attachment that contains results with the APIObject properties on the Object property.

1APIObject[] subscribers = new APIObject[1];
2Subscriber subscriber = new Subscriber();
3subscriber.EmailAddress = "john@example.com";
4subscriber.SubscriberKey = "12345";
5subscriber.Attributes = new AsyncTestSuite.IntegrationFramework.Attribute[2];
6subscriber.Attributes[0] = new AsyncTestSuite.IntegrationFramework.Attribute();
7subscriber.Attributes[0].Name = "FirstName";
8subscriber.Attributes[0].Value = "john";
9subscriber.Attributes[1] = new AsyncTestSuite.IntegrationFramework.Attribute();
10subscriber.Attributes[1].Name = "YearOfBirth";
11subscriber.Attributes[1].Value = "1989";
12subscribers[0] = subscriber;
13CreateOptions co = new CreateOptions();
14co.RequestType = RequestType.Asynchronous;
15co.RequestTypeSpecified = true;
16co.SendResponseTo = new AsyncResponse[1];
17co.SendResponseTo[0] = new AsyncResponse();
18co.SendResponseTo[0].RespondWhen = RespondWhen.OnCallComplete;
19co.SendResponseTo[0].RespondWhenSpecified = true;
20co.SendResponseTo[0].ResponseType = AsyncResponseType.email;
21co.SendResponseTo[0].ResponseAddress = "responses@example.com";
22co.SendResponseTo[0].IncludeResults = true;
23co.SendResponseTo[0].IncludeResultsSpecified = true;
24co.SendResponseTo[0].IncludeObjects = true;
25co.SendResponseTo[0].IncludeObjectsSpecified = true;
26co.SendResponseTo[0].OnlyIncludeBase = true;
27co.SendResponseTo[0].OnlyIncludeBaseSpecified = true;
28CreateResult[] results = integrationFramework.Create(co, subscribers, out requestID, out status);
29Console.WriteLine(results[0].StatusCode);
30Console.WriteLine(results[0].StatusMessage);
31Assert.IsNotNull(results);
32Assert.AreEqual("OK", status);

When the value of IncludeResults is true, the response data included in the email attachment resembles this example.

1<CreateResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2xmlns:xsd="http://www.w3.org/2001/XMLSchema"
3xmlns="http://exacttarget.com/wsdl/partnerAPI">
4  <StatusCode>Error</StatusCode>
5  <StatusMessage>The subscriber is already on the list</StatusMessage>
6  <OrdinalID>0</OrdinalID>
7  <ErrorCode>12014</ErrorCode>
8  <NewID>0</NewID>
9</CreateResult>

When the values of IncludeResults and IncludeObjects are both true, the response resembles this example.

1<CreateResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2xmlns:xsd="http://www.w3.org/2001/XMLSchema"
3xmlns="http://exacttarget.com/wsdl/partnerAPI">
4  <StatusCode>Error</StatusCode>
5  <StatusMessage>The subscriber is already on the list</StatusMessage>
6  <OrdinalID>0</OrdinalID>
7  <ErrorCode>12014</ErrorCode>
8  <NewID>0</NewID>
9  <Object xsi:type="Subscriber">
10    <ObjectID xsi:nil="true" />
11    <EmailAddress>john@example.com</EmailAddress>
12    <Attributes>
13      <Name>FirstName</Name>
14      <Value>Dale</Value>
15    </Attributes>
16    <Attributes>
17      <Name>YearOfBirth</Name>
18      <Value>1989</Value>
19    </Attributes>
20    <SubscriberKey>2345672</SubscriberKey>
21  </Object>
22</CreateResult>

When the values of IncludeResults, IncludeObjects, and OnlyIncludeBase are all true, the response resembles this example.

1<CreateResult xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
2xmlns:xsd="http://www.w3.org/2001/XMLSchema"
3xmlns="http://exacttarget.com/wsdl/partnerAPI">
4  <StatusCode>Error</StatusCode>
5  <StatusMessage>The subscriber is already on the list</StatusMessage>
6  <OrdinalID>0</OrdinalID>
7  <ErrorCode>12014</ErrorCode>
8  <NewID>0</NewID>
9  <Object xsi:type="Subscriber">
10    <ObjectID xsi:nil="true" />
11  </Object>
12</CreateResult>