addList

Creates a new Contact List.

addList

Creates a new Contact List.

Top ↑

Syntax

int addList( string api_key, object list_details );

Parameters

api_key (string)

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

list_details (object)

An object of List details. See remarks below for a description of the values in the list_details object.

Return Value

Returns the ID of the newly created List on success.

Examples

Creating a new List and setting an email address to receive a Notification when Contacts are added:

$list_details = array(
    'folder_id'             => 1234567,         // can be obtained using searchFolders
    'name'                  => 'Example List',
    'on_register_address'   => 'test@example.com',
);

$api = new Api($url, 'YOURAPIKEY');
$new_list_id = $api->invokeMethod('addList', $list_details);
{
    "id": 1,
    "method": "addList",
    "params": [
        "YOURAPIKEY",
        {
            "folder_id": 1234567,
            "name": "Example List",
            "on_register_address": "test@example.com"
        }
    ]
}
{
    "id": 1,
    "result": 123456,
    "error": null
}

Remarks

The following table shows the structure of the list_details object.

Key Type Mandatory Default Description
name string Yes The name of the List.
folder_id int Yes The folder where the List is to be created. See searchFolders.
allow_send_to_duplicates bool No false Set to true to allow messages to be sent to duplicate Contacts which have the same address.
on_register_address string No A comma separated list of addresses which receive a notification message when a Contact subscribes to the List.
on_unsubscribe_address string No A comma separated list of addresses which receive a notification message when a Contact unsubscribes from the List.
on_update_address string No A comma separated list of addresses which receive a notification message when a Contact updates their profile.

By default, the List is created with Email and Mobile Phone Fields. Use addField to add additional Fields to the List.

To add Contacts to the List, see addContacts or subscribeContact.

Error Codes

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

Code Error Description
310 Invalid Method Parameters name is empty or missing from the list_details object.
310 Invalid Method Parameters folder_id is empty or missing from the list_details object.
306 Unable to Load Folder folder_id is not a valid Folder.
317 Invalid Email Address Specified on_register_address contains an invalid email address or mobile number.
302 Undefined Error: Unable to save List An internal error occurred.

See Also