Vision 6

searchPreviousUnsubscribers

Returns the Unsubscribers in the Unsubscriber List that match the search criteria.

searchPreviousUnsubscribers

Returns the Unsubscribers in the Unsubscriber List that match the search criteria.

Top ↑

Syntax

array searchPreviousUnsubscribers(
    string api_key,
  [ int list_id,
    array search_criteria,
    int limit,
    int offset,
    string sort_by,
    string sort_order ] 
);

API Key Access Level required: Standard access

Parameters

api_key (string)

The key required to access the API. See Getting Started for more information.

list_id (int - optional)

The ID of a List of Contacts to search.

search_criteria (array - optional)

An array of search criteria. See the remarks section below for the list of values which are searchable.
If you do not specify search criteria, all previous unsubscribers are returned.

limit (int - optional)

Maximum number of items to return. Defaults to 100

offset (int - optional)

Number of items to skip before beginning to return results. See Using Search Methods for information about using the offset parameter with the limit parameter to include pagination in your results.

sort_by (string - optional)

The name of the value to sort the results by.

sort_order (string - optional)

The order the results are returned in (either ascending or descending). The default is descending. Valid values are:

  • DESC - Sort from highest to lowest (default).
  • ASC - Sort from lowest to highest.

Return Value

Returns an array containing zero or more associative arrays of Unsubscriber details. See the remarks section below for the list of values this method returns.

Examples

In the following example searchPreviousUnsubscribers looks for unsubscribers in List 123456 who have an Email address that ends with .com. In this case, the method returns no more than three results sorted in ascending order on the contact_id Field.

PHP

$api = new Api($url, 'YOURAPIKEY');

$list_id = 123456;

$search_criteria = array(
    array(
        'field' => 'address_type',
        'modifier' => 'exactly',
        'value' => 'email'
    ),
    array(
        'field' => 'address',
        'modifier' => 'contains',
        'value' => 'com'
    )
);

$limit = 3;
$offset = 0;
$sort_by = 'contact_id';
$sort_order = 'ASC';

$result = $api->invokeMethod('searchPreviousUnsubscribers', $list_id, $search_criteria, $limit, $offset, $sort_by, $sort_order);

JSON Request

{
    "id": 1,
    "method": "searchPreviousUnsubscribers",
    "params": [
        "YOURAPIKEY",
        315895,
        [
            {
                "field": "address_type",
                "modifier": "exactly",
                "value": "email"
            },
            {
                "field": "address",
                "modifier": "contains",
                "value": "com"
            }
        ],
        3,
        0,
        "contact_id",
        "ASC"
    ]
}

JSON Response

{
    "id": 1,
    "result": [
        {
            "contact_id": "29",
            "send_id": "0",
            "batch_id": "0",
            "address": "test5@example.com",
            "address_type": "email",
            "unsubscribe_type": "manual",
            "unsubscribe_count": "1",
            "unsubscribe_time": "1354239498",
            "list_id": "315895"
        },
        {
            "contact_id": "30",
            "send_id": "0",
            "batch_id": "0",
            "address": "test3@dom3.com",
            "address_type": "email",
            "unsubscribe_type": "manual",
            "unsubscribe_count": "1",
            "unsubscribe_time": "1359699729",
            "list_id": "315895"
        },
        {
            "contact_id": "31",
            "send_id": "0",
            "batch_id": "0",
            "address": "test4@dom4.com",
            "address_type": "email",
            "unsubscribe_type": "manual",
            "unsubscribe_count": "1",
            "unsubscribe_time": "1359699729",
            "list_id": "315895"
        }
    ],
    "error": null
}

Remarks

The following table shows the values that are returned.

Key Type Searchable Description
list_id int No The List ID. A value of 0 indicates this is an address unsubscribed from all Lists.
contact_id int Yes The ID of the Contact that unsubscribed.
batch_id int Yes The Batch the Contact unsubscribed from. Will be 0 if the Contact did not click on an unsubscribe link in a Message.
send_id int Yes The Contact's Send ID in the Batch.
address string Yes The address that was unsubscribed.
address_type string Yes The type of the address value. Either email or mobile.
unsubscribe_type int Yes How the Contact unsubscribed. Valid values are webform, manual, stop_word and complaint.
unsubscribe_count int Yes The number of Contacts that were unsubscribed.
unsubscribe_time int Yes Timestamp indicating when the Contact unsubscribed.

An address that is unsubscribed from all Lists will have a list_id of 0 and an unsubscribe_count set to the number of Contacts that were unsubscribed across all Lists.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code Error Description
310 Invalid Method Parameters One or more parameters are invalid.
311 Invalid Search Parameter Format Your search criteria are invalid, or your search array is incorrectly formatted.

See Also