BrandMail API - getBatchLinkContacts

Syntax

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

Parameters

api_key (string)

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

batch_id (int)

The ID of the Batch

link (string)

The link you want to query

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 clicked on the link 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 (string - optional)

The name of the value to sort the results by.

sort_order (string - 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 link click information for each List the Batch was sent to. See the remarks section below for the list of values returned.

Examples

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

// setup vars

$batch_id = 1234567;

$link     = 'http://example.com/example.html';

// send a Message to a single Contact in a List

$result = $api->invokeMethod('getBatchLinkStatistics', $batch_id, $link);

{

    "id": 1,

    "method": "getBatchLinkContacts",

    "params": [

        "YOURAPIKEY",

        1234567,

        "http://example.com/example.html"

    ]

}

{

    "id": 1,

    "result": {

        "315907": [

            {

                "send_id": "1116100",

                "link_id": "1489024",

                "link_click_id": "1001173",

                "contact_id": "23319",

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

                "link_name": "Special Offers",

                "link_url": "http://example.com/example.html",

                "links_clicked": "1",

                "click_count": "1",

                "reference": "0",

                "open_country": "00",

                "timestamp": "1360631805",

                "unsubscribe_email": null

            }

        ]

    },

    "error": null

}

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
`timestamp`	int	Yes	Timestamp of when the link was clicked
`link_id`	int	Yes	The link ID
`link_name`	string	Yes	The name of the link
`link_url`	string	Yes	The link URL
`link_click_id`	int	No	The link click ID
`links_clicked`	int	No	The number of links clicked by the Contact
`click_count`	int	No	The number of times the link was clicked
`open_country`	string	No	Country where the contact opened the message
`contact_email`	string	No	The email address for the Contact
`unsubscribe_email`	string	No	The email address that was unsubscribed

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

getBatchLinkContacts