getBatchLinkContacts

Returns a list of Contacts in a Batch that clicked on a specific link.

getBatchLinkContacts

Returns a list of Contacts in a Batch that clicked on a specific link.

Top ↑

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('getBatchLinkContacts', $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

See Also