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