Jump to content

GetCampaignSubscriberClicks()

Retrieve link click information among all subscribers sent an email campaign. Start and end dates can be used to limit search results. Returns a maximum of 200 link clicks per method call.

Parameters

ApiKey (Required)
    Your application authentication key. Click here to find out more.
CampaignReportID (Optional)
    The ID number of the sent email campaign, as seen in the Reports tab.Click here to find out more.
StartIndex (Optional)
    The zero-based index offset at which to start listing the results. If left blank, the list will start at index 0 (i.e. the beginning).

Return Value

On success, this method returns the following information:

  • Subscriber Click Count - the total number of link clicks among all subscribers who were sent the campaign. If this number exceeds 200 (the maximum number of records returned per method call) and you want the entire list, you will need to invoke the method again and use the StartIndex parameter to retrieve the list in chunks.
  • Subscriber Clicks - an array listing the subscribers that clicked each link, and how often:
        URL - the URL behind the link
        Email - the email address of the subscriber
        ListID - the ID of the list to which the subscriber belongs
        Clicks - the number of times the subscriber has clicked on the link

On failure, a SOAP fault exception is thrown with one of the fault codes below.

Usage Notes

For performance reasons, GetCampaignSubscriberClicks returns a maximum of 200 records at a time; to retrieve all subscriber clicks beyond this limit, invoke the method as many times as needed with the appropriate offset. To help, the Subscriber Click Count return value will always be the total number of clicks, not necessarily the total returned by the current invocation.

Note that CampaignReportID values are not the same as CampaignID values. CampaignReportIDs are retrieved from the Reports tab, as explained here.

Be aware that the "Subscriber Click Count" value represents the total number of subscriber-click combinations (i.e. the total number of rows returned under "Subscriber Clicks").  Since it is possible for a subscriber to click a link more than once, we include this count  for each subscriber-click combination, but do not provide it as a separate aggregate total.  In this way, the Subscriber Click Count value is mostly provided to facilitate the return of more than 200 rows.  You can get the total number of link clicks through the CampaignClicks method.

So, for example, while the following data shows the total number of actual clicks (including multiple clicks of the same link by a single subscriber) is 11, the total number of distinct subscriber-click combinations is six (which is the number of Subscriber Clicks rows returned by the method:

Subscriber Link Number of Clicks
Subscriber 1 Link A 1
Subscriber 1 Link C 2
Subscriber 2 Link B 1
Subscriber 2 Link C 3
Subscriber 3 Link A 3
Subscriber 3 Link B 1
  Total: 11

Fault Codes

100 - Invalid API Key
    The API key is not valid or expired

SOAP Sample Request


    
    
        
            
                STRING
                INT
                INT

SOAP Sample Response


    
    
        
            
                INT
                
                    <item>
                        <Email>STRING</Email>
                        <ListID>INT</ListID>
                        <URL>STRING</URL>
                        <Clicks>INT</Clicks>
                    </item>
                    <item> ... </item>

Code Sample - PHP

// Import the eConnect Email API Toolkit
require_once('eConnectEmail_API_Toolkit.php');

$eConnectEmailApi = TheKeyMakerClient('YOUR_API_KEY');

$result = $eConnectEmailApi->GetCampaignSubscriberClicks(CAMPAIGN_ID, START_INDEX);

// Show the results
print 'Response: <pre>';
print_r($result);
print '</pre>';

Code Sample - ASP.NET C#

            TheKeyMaker_v20 api = new TheKeyMaker_v20();
            // Set up input parameters
            CampaignSubscribersParams csParams = new CampaignSubscribersParams();
            csParams.ApiKey = txtApiKey.Text;
            csParams.CampaignReportID = int.Parse(txtGCSCCampaignReportID.Text);
            csParams.StartIndex = (txtGCSCStartIndex.Text.Trim() == "" ? 0 : int.Parse(txtGCSCStartIndex.Text));

            // Invoke method and store result
            ReturnCampaignSubscriberClicks campaignSubsClicks = api.GetCampaignSubscriberClicks(csParams);

            // Display results
            lblResult.Text = FormatValue("Click Count", campaignSubsClicks.SubscriberClickCount.ToString());
            lblResult.Text += "
Showing " + campaignSubsClicks.SubscriberClicks.Length.ToString()
                + " clicks starting at index " + csParams.StartIndex.ToString() + "):
";
            if (campaignSubsClicks.SubscriberClicks.Length > 0)
            {
                lblResult.Text += ""
                    + "";
                foreach (CampaignSubscriberClickResult click in campaignSubsClicks.SubscriberClicks)
                {
                    lblResult.Text += "";
                }
                lblResult.Text += "
URLListIDEmailClicks
" + click.URL + "" + click.ListID.ToString()
                        + "" + click.Email + "" + click.Clicks.ToString() + "
";
            }
            else
            {
                lblResult.Text += "no subscribers match the specified criteria.";
            }