List

The list service is for listing, creating and alteration of lists.


fetchAll

array list.fetchAll( void )

Requests a list of lists. This method has no parameters to specify as it will request all lists regardless of the position within the folder hierarchy.

Return Values

Returns an array of associative arrays. For the possible returned elements see #find



find

array list.find( int listId )

Requests the list details of the single list id requested.

Parameters

listId

ID of the list you're requesting.

Return Values

Returns an associative array. The possible returned elements are as follows:

Name

Type

Description

list_id

int

List Id

folder_id

int

Folder Id

name

string

Name of the list

list_total

int

Total number of recipients in the list

status

string

The lists current usage status

type

string

List type (include or exclude)

created_ts

timestamp

Date and time when the list was created

update_ts

timestamp

Date and time the list was last updated



insert

int list.insert( array data )

Inserts a new list into the current customer space.

Parameters

data

Name

Required

Type

Description

name

yes

string

What you want to name the list

folder_id

yes

int

What folder you want this list to be attached to

type

no

string

The list type: include (default) or suppression

Resource Limit

The number of Lists allowed in the system is limited to 500. This method will return an error if this is exceeded.

Return Values

Returns an int type. The id of the newly created list.



update

bool list.update( int listId, array data )

Updates an existing list using the data specified.

Parameters

listId

ID of the list you want to update.

data

See #insert, however all keys are optional

Return Values

Returns a bool. True on success.



truncate

bool list.truncate( int listId )

Removes all recipients from the specified list.

Parameters

listId

ID of the list you want to empty.

Return Values

Returns true on success, false on failure.



delete

bool list.delete( int listId )

Deletes the specified list id.

Parameters

listId

ID of the list you want to delete.

Return Values

Returns true on success, false on failure.



Deprecated

This method has been superseded by #fetchRecipientsData

fetchRecipients

array list.fetchRecipients( int listId, int limit, int start, string sort, string dir, array filter )

Fetch all recipients from a particular list.

For details of the parameters and return value, see #fetchRecipientsData.



fetchRecipientsData

array list.fetchRecipientsData( int listId, array profileFields, int limit, int start, string sort, string dir, array filter )

Fetch all recipients from a particular list.

A maximum of 5000 records will be returned. Therefore to retrieve the complete list, the function should be iterated in a loop, with each loop's start being increased by your value for limit, until the start value is greater than the list_total returned.

Parameters

listId

ID of the list from which you want to retrieve recipients.

profileFields

Array of IDs of profile fields to include in the result.

limit

The number of records to be returned. If greater than 5000, a value of 5000 will be used.

start

The starting record from which to retrieve limit rows.

sort

Not supported. Parameter kept in place for backwards compatibility.

dir

Not supported. Parameter kept in place for backwards compatibility.

filter

Associative array of column filters. TBC.

Return Values

Returns an associative array:

Key

Type

Comment

list_total

int

total number of records in the list

count

int

total number of records in records

offset

int

reflects the start parameter

limit

int

reflects the limit parameter

sort

string

reflects the sort parameter

dir

string

reflects the dir parameter

records

array

indexed array of recipients, as an associative array. See #fetchRecipient



fetchRecipient

array list.fetchRecipient( int listId, int recipientId )

Fetch data on a single recipient.

Parameters

listId

ID of the list.

recipientId

ID of the recipient you want to retrieve.

Return Values

Returns an associative array:

Key

Type

Comment

record_type

string

one of 'campaign', 'seed', 'both'

subscribed

int

bool as int

unsubscribe_method

string

method by which the recipient unsubscribed, see #insertRecipient

update_ts

timestamp

datetime of the last update

recipient_id

int

recipient's unique identfier

email_address

string


<Folder/Profile.Field>,...

string

A key and value are returned for each profile field



insertRecipient

array list.insertRecipient( int listId, array data )

Adds a recipient to a particular list.

This should only be used on an individual basis.
To insert multiple recipients, see the List_Import service.

Parameters

listId

ID of the list.

data

Associative array of recipient data:

Key

Required

Type

Comment

email_address

Yes

string


subscribed

No

bool

Subscription status of the recipient on the list

unsubscribe_method

No

string

See below (If entered, subscribed must also be specified)

record_type

No

string

one of 'campaign', 'seed', 'both'

unsubscribe_method

Value

Unsubscribe via...

manual

...the interface

feedback

...feedback loop

link

...link from an email

form

...form from an email

api

...api call

Return Values

Returns an associative array. See #fetchRecipient.



updateRecipient

array list.udpateRecipient( int listId, int recipientId, array data )

Update a recipient's details.

Parameters

listId

ID of the list containing the recipient.

recipientId

ID of the recipient you want to update.

data

See #insertRecipient.

Profile data can also be specified, where the key is the profile field path.

array(
    'Personal.FirstName' => 'Test',
    'Personal.FirstName' => 'Person',
    'Address/Home.Street' => 'Example Close',
    'Address/Home.Town' => 'Sample City'
);

The inclusion of profile data here is a convenience for when you are also updating the recipient's list details.
Profile data is not associated to a list, so if you just wish to update a recipient's profile data, use recipient.update instead.

Return Values

Returns an associative array. See #fetchRecipient.



deleteRecipient

bool list.deleteRecipient( int listId, int recipientId )

Removes a particular recipient from the specified list.

Parameters

listId

ID of the list from which you want to delete the recipient.

recipientId

ID of the recipient you want to be removed.

Return Values

Returns an boolean true on completion.

Service

list

Methods