legacy.retrieve_unsub

‹ BACK TO API PAGE

Description

This method returns a list of contacts that were unsubscribed based upon 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

  1. This method only supports the XML response type. The PHP response type is not available for this method.
  2. 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
email 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 from. 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  
email 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 Date that the contact's record was unsubscribed. Date is in YYYY-MM-DD format 2010-04-10
method_unsubscribed The means that the contact unsubscribed. Options include:
  • Survey Page – if the opt out occurred by any of the following mechanisms:
    • clicked the "unsubscribe" link within a hosted subscriber preference page. The preference page is either the standard signup form or a custom signup form.
    • the Legacy.manage_subscriber API method call where the <optout> element is set to 'Y'
  • System Opt-out – if the opt out occurred by any of the following mechanisms:
    • the contact has been explicitly unsubscribed from within Empower Enterprise by selecting Subscribers >> Opt Out Subscriber or Subscribers >> Import to Optout.
    • the Legacy.delete_subscribers API method call where the <optout> element is set to 'Y'
  • List-Unsubscribe – the contact has unsubscribed by clicking the "Unsubscribe" button provided within email clients of those ISPs supporting this capability (example: Gmail).
  • Spam Complaint – the contact has clicked the "This is SPAM" button within his email client.
  • Mapp EchoSystem – the contact has been explicitly deleted from within Empower Enterprise via a reseller's account by any of the following mechanisms:
  • Email Marketing System – the contact has been explicitly deleted from within Empower Enterprise via a reseller's white labeled account by the same mechanisms as above with Mapp EchoSystem
 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:
  • 0 – did not initiate the opt-out request
  • 1 – initiated the opt-out request

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>

Back to API Reference Guide