getBatchContacts

Returns a list of Contacts in a Batch that match the search criteria.

getBatchContacts

Returns a list of Contacts in a Batch that match the search criteria.

Top ↑

Syntax

array getBatchContacts(
    string api_key,
    int batch_id,
  [ array search_criteria,
    int limit,
    int offset,
    int sort_by,
    int sort_order ] 
);

Parameters

api_key (string)

The key required to access the API. See Getting Started for more information.

batch_id (int)

The Batch Id.

search_criteria (array - optional)

An array of search criteria. See the remarks section below for the list of values which are searchable.
If you do not specify search criteria, all Contacts in the Batch are returned.

limit (int - optional)

Maximum number of items to return.

offset (int - optional)

Number of items to skip before beginning to return results. See Using Search Methods for information about using the offset parameter with the limit parameter to include pagination in your results.

sort_by (int - optional)

The name of the value to sort the results by.

sort_order (int - optional)

The order the results are returned in (either ascending or descending). The default is descending. Valid values are:

  • DESC - Sort from highest to lowest (default).
  • ASC - Sort from lowest to highest.

Return Value

Returns an associative array indexed by List ID containing an array of zero or more associative arrays of Contact information for each List the Batch was sent to. See the remarks section below for the list of values returned for each Contact.

Examples

    $bacth_id   = 123;
    $limit      = 2;
    $offset     = 0;
    $sort_by    = 'Email';
    $sort_order = 'ASC';
    $search_criteria  = array(
        array('Email', 'contains', 'test')
    );

    $api = new Api($url, 'YOURAPIKEY');
    $result = $api->invokeMethod('getBatchContacts', $bacth_id, $search_criteria, $limit, $offset, $sort_by, $sort_order);
{
    "id": 1,
    "method": "getBatchContacts",
    "params": [
        "YOURAPIKEY",
        123,
        [
            [
                "Email",
                "contains",
                "test"
            ]
        ],
        2,
        0,
        "Email",
        "ASC"
    ]
}
{
    "325393": [
        {
            "send_id": "1000001",
            "contact_id": "2",
            "contact_email": "test2@example.com",
            "unsubscribe_email": null,
            "unsubscribe_time": null,
            "unsubscribe_id": null,
            "unsubscribe_count": null,
            "is_temporary_bounce": "1",
            "links_clicked": "0",
            "open_type": "not_opened",
            "send_time": "1361509198",
            "bounce_smtp_error_code": "0",
            "bounce_description": "No Error",
            "open_count": "0",
            "open_country": "0",
            "reference": "0",
            "send_status": "completed",
            "updated_profile_count": "0",
            "first_open_time": "0",
            "last_open_time": "0",
            "first_updated_profile_time": "0",
            "first_unsubscribe_time": "0",
            "first_permanent_bounce_time": "0",
            "first_temporary_bounce_time": "0",
            "first_bounce_time": "0"
        },
        {
            "send_id": "1000002",
            "contact_id": "3",
            "contact_email": "test3@example.com",
            "unsubscribe_email": null,
            "unsubscribe_time":null,
            "unsubscribe_id": null,
            "unsubscribe_count": null,
            "is_temporary_bounce": "1",
            "links_clicked": "0",
            "open_type": "not_opened",
            "send_time": "1361509198",
            "bounce_smtp_error_code": "0",
            "bounce_description": "No Error",
            "open_count": "0",
            "open_country": "0",
            "reference": "0",
            "send_status":"completed",
            "updated_profile_count":"0",
            "first_open_time": "0",
            "last_open_time": "0",
            "first_updated_profile_time": "0",
            "first_unsubscribe_time": "0",
            "first_permanent_bounce_time": "0",
            "first_temporary_bounce_time": "0",
            "first_bounce_time": "0"
        }
    ]
}

Remarks

The following table shows the values that are returned.

Key Type Searchable Description
send_id int Yes The send ID
contact_id int Yes The contact ID
contact_email string Yes The contact email address
unsubscribe_email string Yes The email address that was unsubscribed
unsubscribe_time int Yes The time the contact unsubscribed
unsubscribe_id int Yes The unsubscribe id
unsubscribe_count int Yes The number of times the contact unsubscribed
updated_profile_count int Yes The number of times the Contact updated their profile
send_status string Yes Status of the send. Valid values are pending, completed, failed or split_sms.
send_time int Yes Timestamp when the Message was sent to the Contact
open_type string Yes Type of the email open. Valid values are not_opened, html, text or sms.
open_count int Yes Total number of times the Contact opened the Message
open_country string Yes Country where the contact opened the message
bounce_smtp_error_code string Yes The SMTP bounce error code
bounce_description string No Description of the bounce
is_temporary_bounce int Yes Value indicating whether the contact bounced temporarily
first_open_time int Yes Timestamp when the Contact first opened the Message
last_open_time int Yes Timstamp of when the Contact last opened the Message
first_updated_profile_time int Yes Timestamp of when the Contact first updated their profile
first_unsubscribe_time int Yes Timestamp of when the Contact first unsubscribed
first_permanent_bounce_time int Yes Timestamp of when the Contact was identified as a permanent bounce
first_temporary_bounce_time int Yes Timestamp of when the Contact was identified as a temporary bounce
first_bounce_time int Yes Timestamp of when the Message sent to the Contact first bounced
links_clicked int No The total number of links clicked by the Contact

You can also search on any of the List Fields for the Contacts in the Batch (Email, First Name, Last Name etc).

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code Error Description
308 Unable to Load Batch batch_id is not a valid Batch
311 Invalid Search Parameter Format search_critera is not valid

See Also

Method References
Popular Pages