BrandMail API - addList

Syntax

int addList( string api_key, array list_details );

Parameters

api_key (string): The key required to access the API. See Getting Started for more information.
list_details (array): An associative array of List details. See remarks below for a description of the values in the list_details array.

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 array.

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` array.
`310`	Invalid Method Parameters	`folder_id` is empty or missing from the `list_details` array.
`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.

addList