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: |
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