BrandMail API - searchLists

Syntax

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

Parameters

api_key (string)

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

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 Lists are returned.

limit (int - optional)

Maximum number of items to return.

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 List details. See the remarks section below for the list of values this method returns.

Examples

Retrieve all Lists in the Prospects Folder, ordered by name.

$search_criteria = array(

    array('folder_name', 'exactly', 'Prospects'),

);

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

$lists = $api->invokeMethod('searchLists', $search_criteria, 0, 0, 'name', 'ASC');

  // loop over result

foreach ($lists as $list_details) {

    print "Found ". $list_details['name'] ."\n";

}

{

    "id": 1,

    "method": "searchLists",

    "params": [

        "YOURAPIKEY",

        [

            ["folder_name", "exactly", "Prospects"],

        ],

        0,

        0,

        "name",

        "ASC"

    ]

}

{

    "id": 1,

    "result": [

        {

            "id": 1234567,

            "creator_user_id": 23456,

            "name": "Example List",

            "creation_time": 1323139542,

            "last_modified_time": 1323139542,

            "on_register_address": "alice@example.com,bob@example.com",

            "on_update_address": "",

            "on_unsubscribe_address": "",

            "disallow_duplicate_contacts": false,

            "folder_id": 34567,

            "contact_count": 8,

            "country_code": 61,

            "virtual_number": 0,

            "sms_stop_words": "REMOVE ME,UNSUBSCRIBE",

            "sms_response_action": "do_nothing",

            "sms_response_field_ids": "",

            "folder_name": "Prospects",

            "address_types": "email,mobile",

            "creator_name": "Bob Smith",

            "allow_send_to_duplicates": false

        }

    ],

    "error":null

}

Remarks

The following table shows the values that are returned.

Key	Type	Searchable	Description
`id`	int	Yes	List ID.
`name`	string	Yes	The name of the List.
`allow_send_to_duplicates`	bool	Yes	When set to true, allows message to be sent to duplicate Contacts (Contacts with the same address).
`contact_count`	int	Yes	The number of Contacts in the List.
`country_code`	int	Yes	The default country dialling prefix used for Contacts in the List.
`creation_time`	int	Yes	Timestamp indicating when the List was created.
`creator_name`	string	Yes	The name of the User who created the List.
`creator_user_id`	int	Yes	The User who created the List.
`disallow_duplicate_contacts`	bool	Yes	When set to true, duplicate Email addresses cannot be added.
`folder_id`	int	Yes	The ID of the Folder containing the List.
`folder_name`	string	Yes	The name of the Folder containing the List.
`last_modified_time`	int	Yes	Timestamp indicating when the List was last modified.
`on_register_address`	string	Yes	A comma separated list of addresses that receive a Notifications when a Contact subscribes to the List.
`on_unsubscribe_address`	string	Yes	A comma separated list of addresses that receive a Notifications when a Contact unsubscribes from the List.
`on_update_address`	string	Yes	A comma separated list of addresses that receive a Notifications when a Contact updates their profile.
`sms_stop_words`	string	Yes	A comma separated list of SMS stop words that Contacts can reply with to unsubscribe.
`sms_response_action`	string	Yes	The action to perform when an SMS response is received. Valid values are `do_nothing`, `add_new_contact` or `update_contact`.
`sms_response_field_ids`	string	Yes	A comma separated list of Field ID's where Contact SMS responses are saved.
`virtual_number`	string	Yes	The virtual number used when Contacts subscribe to the List via SMS. Also the number the system uses when sending SMS messages.
`address_types`	string	No	A comma separated list of address Field types in the List. Valid values are `email` or `mobile`.

Error Codes

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

Code	Error	Description
`311`	Invalid Search Parameter Format	`search_critera` is not valid

searchLists