- 3 Minutes to read
- Print
- DarkLight
legacy.retrieve_unsub
- 3 Minutes to read
- Print
- DarkLight
General Information
This method returns a list of contacts that were unsubscribed based on a specific date, a date range, or a specific message. You can also use this method to verify whether a specific individual has been unsubscribed.
Usage Notes
This method only supports the XML response type. The PHP response type is not available for this method.
The total count of opt-outs in this method may be more than the number of subscribers which are returned in a search for individuals who have opted out via that specific message. The reason for this disparity is that some ISPs require total anonymity as to which subscriber opted out from any specific message when they send back an automated complaint.
Arguments
Field | Description | Field Type | Required | Example |
---|---|---|---|---|
date_deleted1 | A specific date when subscribers were deleted or the beginning of a date range when subscribers were deleted when used in conjunction with date_deleted2 | Date (in YYYY-MM-DD format) | Conditional; required if <date_deleted2> is provided. Also is required if <email> is not provided. | 2010-04-01 |
date_deleted2 | The end of a date range when subscribers were deleted. | Date (in YYYY-MM-DD format) | Conditional; required if <date_deleted1> is provided. | 2010-05-01 |
A specific subscriber's email address to confirm that it has been unsubscribed. | String | No | john_smith@example.com | |
external_id | An identifier defined within an external system. If this element is included with the <email> element, then the search for the subscriber record will be based on both the external ID and the email address. | |||
mess_id | A message ID identifying a message from which contacts have unsubscribed. | Number | No | 42342 |
Response
Field | Description | Example |
---|---|---|
manifest | This element is an enumeration of <deleted_contact_data> elements. It contains the full set of unsubscribed contact data. | |
deleted_contact_data | This element is the wrapper of the specific elements defining the unsubscribed contact | |
The email address of the unsubscribed contact. | john_smith@example.com | |
external_id | The subscriber's identifier defined within an external system. This element will be included in the response only if the External ID feature is enabled for your account. | |
date_deleted | The date that the contact's record was unsubscribed. Date is in YYYY-MM-DD format | 2010-04-10 |
method_unsubscribed | The method with which the contact unsubscribed. Options include:
| Survey Page |
mess_id | The ID number of the email that the recipient unsubscribed from. If the contact unsubscribed from a different mechanism (see <method_unsubscribed> above) then this element will be returned empty. | 42324 |
initiated_optout | A boolean value indicating whether the subscriber is the one who initiated the opt-out where:
This element will be included only when the External ID feature is enabled for your account. |
Response Codes
Response Code | Response Text | Description |
---|---|---|
432 | Invalid search parameters | Any invalid combination or values provided in the request. |
471 | date_deleted1 must be in YYYY-MM-DD format | Invalid data format provided in the input. |
472 | date_deleted2 must be in YYYY-MM-DD format | Invalid data format provided in the input. |
473 | date_deleted1 must be earlier than date_deleted2 | Invalid combination of elements provided in the input. |
Example Post
The following POSTed XML message retrieves the list of contacts that unsubscribed between April and May 2010.
<methodCall>
<methodName>legacy.retrieve_unsub</methodName>
<date_deleted1>2010-04-01</date_deleted1>
<date_deleted2>2010-05-31</date_deleted2>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>
<legacy.retrieve_unsub>
</methodName>
<responseData>
<manifest>
<deleted_contact_data>
<email>john_smith@example.com</email>
<date_deleted>2010-04-13</date_deleted>
<method_unsubscribed>Survey Page</method_unsubscribed>
<mess_id>42324</mess_id>
</deleted_contact_data>
<deleted_contact_data>
<email>subscriber@gmail.com</email>
<date_deleted>2010-04-10</date_deleted>
<method_unsubscribed>System Opt-out</method_unsubscribed>
<mess_id></mess_id>
</deleted_contact_data>
</manifest>
</responseData>
<responseNum>1</responseNum>
</item>
</methodResponse>