--- schema_version: "1" id: ef641e00d70b48936c5fa5b38f4349e5f466b3dbc47a59cfd0d7982dca70997b title: Response Options collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/guides/mc-apis/async_guide_response_options.md canonical_url: https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/async_guide_response_options.html source_site: developer.salesforce.com content_type: documentation content_hash: 1a193099f5749782bb85a35c9c0533d51da096951891d4c0aad8b082baa41a49 products: - Marketing Cloud Engagement APIs and Programmatic Languages - Marketing Cloud --- # 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.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 ```csharp APIObject[] subscribers = new APIObject[1]; Subscriber subscriber = new Subscriber(); subscriber.EmailAddress = "john@example.com"; subscriber.SubscriberKey = "23456789"; /* * Attribute selection: * For best performance ensure the triggered send is using fields that exist on a data extension as attributes * * HTML__ is a prefix valuable when sending larger than 2000 characters through a legacy subscriber attribute * The HTML__ prefix is not neccessary for data extension fields. */ subscriber.Attributes = new AsyncTestSuite.IntegrationFramework.Attribute[2]; subscriber.Attributes[0] = new AsyncTestSuite.IntegrationFramework.Attribute(); subscriber.Attributes[0].Name = "FirstName"; subscriber.Attributes[0].Value = "John"; subscriber.Attributes[1] = new AsyncTestSuite.IntegrationFramework.Attribute(); subscriber.Attributes[1].Name = "YearOfBirth"; subscriber.Attributes[1].Value = "1989"; subscribers[0] = subscriber; CreateOptions co = new CreateOptions(); co.RequestType = RequestType.Asynchronous; co.RequestTypeSpecified = true; co.SendResponseTo = new AsyncResponse[1]; co.SendResponseTo[0] = new AsyncResponse(); co.SendResponseTo[0].ConversationID = "firsttest"; co.SendResponseTo[0].RespondWhen = RespondWhen.OnCallComplete; co.SendResponseTo[0].RespondWhenSpecified = true; co.SendResponseTo[0].ResponseType = AsyncResponseType.HTTPPost; co.SendResponseTo[0].ResponseAddress = "https://dev.example.com/partneremail"; co.SendResponseTo[0].IncludeResults = true; co.SendResponseTo[0].IncludeResultsSpecified = true; co.SendResponseTo[0].IncludeObjects = true; co.SendResponseTo[0].IncludeObjectsSpecified = true; CreateResult[] results = integrationFramework.Create(co, subscribers, out requestID, out status); Console.WriteLine(results[0].StatusCode); Console.WriteLine(results[0].StatusMessage); Assert.IsNotNull(results); Assert.AreEqual("OK", status); ``` ### Sample C# Result ```cs // Publicly Available ASPX Web Page string requestID = Request.Form["RequestID"]; string conversationID = Request.Form["ConversationID"]; string overallStatusCode = Request.Form["OverallStatusCode"]; string statusCode = Request.Form["StatusCode"]; string statusMessage = Request.Form["StatusMessage"]; // The error code associated with the first errored object (the one that stopped the conversation) string errorCode = Request.Form["ErrorCode"]; string requestType = Request.Form["RequestType"]; string resultType = Request.Form["ResultType"]; // Optional and may be large string resultDetailXML = Request.Form["ResultDetailXML"]; string sequenceCode = Request.Form["SequenceCode"]; switch (overallStatusCode) { case "OK": // log the conversationID successful break; case "Has Error": // Handle Errors // Submit new conversation if needed break; case "Error": // Handle Errors // Submit new conversation if needed break; } ``` ```csharp APIObject[] subscribers = new APIObject[1]; Subscriber subscriber = new Subscriber(); subscriber.EmailAddress = "john@example.com"; subscriber.SubscriberKey = "23456789"; /* * Attribute selection: * For best performance ensure the triggered send is using fields that exist on a data extension as attributes * * HTML__ is a prefix valuable when sending larger than 2000 characters through a legacy subscriber attribute * The HTML__ prefix is not neccessary for data extension fields. */ subscriber.Attributes = new AsyncTestSuite.IntegrationFramework.Attribute[2]; subscriber.Attributes[0] = new AsyncTestSuite.IntegrationFramework.Attribute(); subscriber.Attributes[0].Name = "FirstName"; subscriber.Attributes[0].Value = "John"; subscriber.Attributes[1] = new AsyncTestSuite.IntegrationFramework.Attribute(); subscriber.Attributes[1].Name = "YearOfBirth"; subscriber.Attributes[1].Value = "1989"; subscribers[0] = subscriber; CreateOptions co = new CreateOptions(); co.RequestType = RequestType.Asynchronous; co.RequestTypeSpecified = true; co.SendResponseTo = new AsyncResponse[1]; co.SendResponseTo[0] = new AsyncResponse(); co.SendResponseTo[0].ConversationID = "firsttest"; co.SendResponseTo[0].RespondWhen = RespondWhen.OnCallComplete; co.SendResponseTo[0].RespondWhenSpecified = true; co.SendResponseTo[0].ResponseType = AsyncResponseType.HTTPPost; co.SendResponseTo[0].ResponseAddress = "https://dev.example.com/partneremail"; co.SendResponseTo[0].IncludeResults = true; co.SendResponseTo[0].IncludeResultsSpecified = true; co.SendResponseTo[0].IncludeObjects = true; co.SendResponseTo[0].IncludeObjectsSpecified = true; CreateResult[] results = integrationFramework.Create(co, subscribers, out requestID, out status); Console.WriteLine(results[0].StatusCode); Console.WriteLine(results[0].StatusMessage); Assert.IsNotNull(results); Assert.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. ```csharp RetrieveRequest rr = new RetrieveRequest(); rr.ObjectType = "ResultMessage"; rr.Properties = new string[] { "CreatedDate", "RequestID", "ConversationID", "CallsInConversation", "SequenceCode", "StatusCode", "ErrorCode", "StatusMessage" }; SimpleFilterPart sfp = new SimpleFilterPart(); sfp.Property = "RequestID"; sfp.SimpleOperator = SimpleOperators.equals; sfp.Value = new string[] {"2519c614-6817-4e9e-a6e1-26b7d160c8b5"}; rr.Filter = sfp; APIObject[] results; String status = integrationFramework.Retrieve(rr, out requestID, out results); // Will return a maximum of 2500 without paging support Console.WriteLine(String.Format("Number of Results:\t{0}", results.Length)); Console.WriteLine("Result Details"); Console.WriteLine("--------------------------"); Console.WriteLine("CreatedDate\tRequestID\tConversationID\tCallsInConversation\tSequenceCode\tStatus\tErrorCode\tMessage"); foreach (APIObject result in results) { ResultMessage resultMsg = result as ResultMessage; 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)); } ``` 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.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. ```csharp APIObject[] subscribers = new APIObject[1]; Subscriber subscriber = new Subscriber(); subscriber.EmailAddress = "john@example.com"; subscriber.SubscriberKey = "12345"; subscriber.Attributes = new AsyncTestSuite.IntegrationFramework.Attribute[2]; subscriber.Attributes[0] = new AsyncTestSuite.IntegrationFramework.Attribute(); subscriber.Attributes[0].Name = "FirstName"; subscriber.Attributes[0].Value = "john"; subscriber.Attributes[1] = new AsyncTestSuite.IntegrationFramework.Attribute(); subscriber.Attributes[1].Name = "YearOfBirth"; subscriber.Attributes[1].Value = "1989"; subscribers[0] = subscriber; CreateOptions co = new CreateOptions(); co.RequestType = RequestType.Asynchronous; co.RequestTypeSpecified = true; co.SendResponseTo = new AsyncResponse[1]; co.SendResponseTo[0] = new AsyncResponse(); co.SendResponseTo[0].RespondWhen = RespondWhen.OnCallComplete; co.SendResponseTo[0].RespondWhenSpecified = true; co.SendResponseTo[0].ResponseType = AsyncResponseType.email; co.SendResponseTo[0].ResponseAddress = "responses@example.com"; co.SendResponseTo[0].IncludeResults = true; co.SendResponseTo[0].IncludeResultsSpecified = true; co.SendResponseTo[0].IncludeObjects = true; co.SendResponseTo[0].IncludeObjectsSpecified = true; co.SendResponseTo[0].OnlyIncludeBase = true; co.SendResponseTo[0].OnlyIncludeBaseSpecified = true; CreateResult[] results = integrationFramework.Create(co, subscribers, out requestID, out status); Console.WriteLine(results[0].StatusCode); Console.WriteLine(results[0].StatusMessage); Assert.IsNotNull(results); Assert.AreEqual("OK", status); ``` When the value of `IncludeResults` is `true`, the response data included in the email attachment resembles this example. ```xml Error The subscriber is already on the list 0 12014 0 ``` When the values of `IncludeResults` and `IncludeObjects` are both `true`, the response resembles this example. ```xml Error The subscriber is already on the list 0 12014 0 john@example.com FirstName Dale YearOfBirth 1989 2345672 ``` When the values of `IncludeResults`, `IncludeObjects`, and `OnlyIncludeBase` are all `true`, the response resembles this example. ```xml Error The subscriber is already on the list 0 12014 0 ```