BrandMail API - getBatchOpened

Syntax

array getBatchOpened(
    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 that have opened the Message 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', 'james')

    );

    $api = new Api($url, 'YOURAPIKEY');

    $result = $api->invokeMethod('getBatchOpened', $bacth_id, $search_criteria, $limit, $offset, $sort_by, $sort_order);

{

    "id": 1,

    "method": "getBatchOpened",

    "params": [

        "YOURAPIKEY",

        123,

        [

            [

                "Email",

                "contains",

                "test"

            ]

        ],

        2,

        0,

        "Email",

        "ASC"

    ]

}

{

    "46546": [

        {

            "send_id": "78989798",

            "contact_id": "2",

            "contact_email": "james@example.com",

            "unsubscribe_email": null,

            "unsubscribe_time": null,

            "unsubscribe_id": null,

            "unsubscribe_count": null,

            "is_temporary_bounce": null,

            "links_clicked": "0",

            "open_type": "html",

            "send_time": "1361509198",

            "bounce_smtp_error_code": "0",

            "bounce_description": "No Error",

            "open_count": "1",

            "open_country": "0",

            "reference": "0",

            "send_status": "completed",

            "updated_profile_count": "0",

            "first_open_time": "1361513533",

            "last_open_time": "1361513533",

            "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

getBatchOpened