Recipient
The recipient service allows for listing, creating and alteration of recipients. Recipients are the email recipients of the email campaign that you will be sending out.
fetchLists
array recipient.fetchLists ( int recipientId )Gets lists to which the recipient belongs.
Parameters
recipientId
Recipient's unique identifier.
Return Values
Indexed array of associative array for each list. Data returned for each list:
Key | Type | Comment |
|---|---|---|
recipient_id | int | recipient's unique identfier |
list_id | int | list's unique identifier |
record_type | string | one of 'campaign', 'seed', 'both' |
subscribed | int | bool as int |
unsubscribe_method | string | method by which the recipient unsubscribed |
update_ts | timestamp | datetime of the last update |
Deprecated
This method has been deprecated and will be removed in a future version.
searchLists
array recipient.find( string emailAddress )Returns details on the recipient specified.
Parameters
emailAddress
Email address of the recipient to retrieve.
Return Values
Returns an array of assocative array. The possible values returned are as follows:
Name | Type | Description |
|---|---|---|
email_address | string | recipient's email address |
recipient_id | int | recipient's unique system identifier |
record_type | string | campaign, seed, or both |
subscribed | bool | Whether the client is subscribed to the list. true = subscribed, false = unsubscribed |
list_id | int | list's unique system identifier |
list_status | string | current list status |
list_name | string | list's name |
list_type | string | include, exclude |
find
array recipient.find ( int recipient_id )Find a recipient by ID.
Parameters
recipient_id
Recipient's unique identifier.
Return Values
Associative array:
Key | Type | Comment |
|---|---|---|
recipient_id | int | recipient's unique identfier |
email_address | string | |
domain_name | string | email domain |
update_ts | timestamp | datetime of the last update |
insert
int recipient.insert( array data )Inserts a new recipient into the current customer space.
This should only need to be used in very special circumstances.
This should not be used for inserting a new recipient to be added to a list.
To insert new recipients into a list, see the list.insertRecipient method.
If you're unsure which method is right for your application, please contact Support, using the details listed in the software's Help->About dialog.
Parameters
data
An associative array of profile data. The key email_address is required.
Profile data should be sent as a nested array of named profiles and profile fields. Please see the example below for the clearest explanation.
array(
'email_address' => 'test@example.com',
'profile' => array(
'Personal' => array(
'FirstName' => 'Test',
'Surname' => 'Person',
),
'Address/Home' => array(
'Street' => 'Example Close',
'Town' => 'Sample City'
)
)
);
Return Values
Returns an int type. The id of the newly created recipient.
update
bool recipient.update( int recipientId, array data )Updates an existing recipient using the data specified.
Parameters
data
Similar to the format used setting the profile data via #insert:
array(
'Personal' => array(
'FirstName' => 'Test',
'Surname' => 'Person',
),
'Address/Home' => array(
'Street' => 'Example Close',
'Town' => 'Sample City'
)
);
Return Values
Returns a bool. True on success.
updateByEmailAddress
bool recipient.updateByEmailAddress( string emailAddress, array data )Updates an existing recipient using the data specified.
Parameters
data
See #update.
Return Values
Returns a bool. True on success.
findByEmailAddress
int|null recipient.findByEmailAddress ( string emailAddress )Returns the recipient ID for an email address.
Parameters
emailAddress
Email address of the recipient to retrieve.
Return Values
Returns the recipient ID if found, null if otherwise
findEmailAddress
array recipient.findEmailAddress ( string searchString, string operator )Returns the recipient IDs matching the search parameters.
Parameters
searchString
Text for which to search in the email_address.
operator
Logic for the search:
Value | Description |
|---|---|
equals | |
contains | |
startswith | |
endswith |
Return Values
Returns an index array of recipients found. For the data returned, see #find.
fetchProfileDataByRecipientId
array recipient.fetchProfileDataByRecipientId ( int recipientId, array profileDescriptions )Fetch profile data for a recipient, found by their recipientId.
Parameters
profileDescriptions
Indexed array of full profile field paths.
array(
'My Profile.Firstname',
'My Profile.Surname',
'Other Profile.Last order',
'Demo/Master.DOB',
);
Return Values
Returns an associative array of recipient profile data.
fetchProfileDataByEmailAddress
array recipient.fetchProfileDataByEmailAddress ( string emailAddress, array profileDescriptions )Fetch profile data for a recipient, found by their email address
Uses the same format of parameters and return values as #fetchProfileDataByRecipientId.
fetchSentEmailsByRecipientId
array recipient.fetchSentEmailsByRecipientId ( int recipientId )Fetch a list of email ids sent to a recipient, by recipientId.
Return Values
Returns an array of associative arrays containing email_id and sent_ts.
fetchSentEmailsByEmailAddress
array recipient.fetchSentEmailsByEmailAddress ( string emailAddress )Fetch a list of email ids sent to a recipient, by email address
Uses the same format of return values as #fetchSentEmailsByRecipientId.
fetchModifedRecipients
array recipient.fetchModifedRecipients ( string timestamp, array profileDescriptions, int limit, int start )Fetch recipients and their profile data which have been updated since the provided timestamp.
The method will check for updates to the recipient, and the profiles included in profileDescriptions.
Parameters
timestamp
Datetime string in an ISO 8601 compliant format, eg. yyyy-mm-dd hh:mm:ss
profileDescriptions
See #fetchProfileDataByRecipientId.
limit
Maximum number of records to return.
start
Start position for fetching paginated results.
Return
Returns an indexed array of associative arrays.
Each record will contains details of the recipient including its update timestamp; the requested profile fields; and an update timestamp for each of the requested profiles.
Service
recipient
Methods