legacy.retrieve_unsub
    • 3 Minutes to read
    • Dark
      Light

    legacy.retrieve_unsub

    • Dark
      Light

    Article summary

    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

    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.

    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

    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  – 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>


    Was this article helpful?