Jump to content

ReturnActive()

Returns a list of the active subscribers for the given contact list, optionally filtered by date added to list.  For performance reasons, a maximum of 200 subscribers is returned at a time; the Start Index parameter is used to return subscribers beyond the initial 200.

Parameters

ApiKey (Required)
    Your application authentication key. Click here to find out more.
ListID (Required)
    The ID number of the list whose active subscribers you wish to retrieve. Click here to find out more.
StartIndex (Optional)
    The zero-based index offset at which to start listing subscribers. If left blank, the list will start at index 0 (i.e. the beginning).
StartDate (Optional) (was "Date" in version 2.0)
EndDate (Optional) (new in version 2.1)
    Allows for filtering of subscribers based on the date they subscribed to the specified list.  Dates can be specified in YYYY-MM-DD, MM/DD/YYYY, or ISO 8601 (YYYY-MM-DDThh:mm:ss.sTZD) format.  When StartDate (Date in version 2.0) is specified, the method will only return subscribers who were added on or after the date provided; if EndDate is specified, subscribers added to the list before that date/time are returned.  When using this date filtering, the Subscriber Count value will reflect the applied filtering.  If StartDate is left blank, the effective start date filter is the beginning of time; if EndDate is left blank, the effective end date is the end of time (or "Now + 1 second," if you will).  If both StartDate and EndDate are left blank, the Subscriber Count will reflect the total number of active subscribers in the list.

Return Value

On success, this method returns the following information:

  • Subscriber Count - the total number of subscribers with an active status in the list; if date filtering is in effect, this number will reflect any filtering
  • Subscribers - an array containing the email address of each active subscriber in the list

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

Usage Notes

ReturnActive returns only 200 subscribers at a time, for performance reasons. If the returned Subscriber Count exceeds 200, invoke ReturnActive again for each subsequent 200, specifying the appropriate StartIndex offset parameter each time.

If the Date parameter is specified, the Subscriber Count value will reflect the total number of active subscribers that fit the date filter.

Fault Codes

200 - Invalid ListID
    The Associated List is not valid
100 - Invalid API Key
    The API key is not valid or expired

SOAP Sample Request


    
    
        
            
                STRING
                INT
                INT
                STRING

SOAP Sample Response


    
    
        
            
                INT
                
                    
                        STRING
                    
                     ...

Code Sample - PHP

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

$eConnectEmailApi = TheKeyMakerClient('YOUR_API_KEY');

$result = $eConnectEmailApi->ReturnActive(LIST_ID, START_INDEX, 'START_DATE');

// 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
            EmailDateParams emaildateParams = new EmailDateParams();
            emaildateParams.ApiKey = txtApiKey.Text;
            emaildateParams.ListID = int.Parse(txtRAListID.Text);
            emaildateParams.StartIndex = txtRAStartIndex.Text.Trim() == "" ? 0 : int.Parse(txtRAStartIndex.Text);
            emaildateParams.Date = txtRADate.Text;

            // Invoke method and store result
            ReturnEmails raReturn = api.ReturnActive(emaildateParams);

            // Display results
            lblResult.Text = FormatValue("Total # of Active Subscribers", raReturn.SubscriberCount.ToString())
                + "
Showing " + raReturn.Subscribers.Length.ToString() + " subscribers starting at index "
                + (txtRAStartIndex.Text.Trim() == "" ? "0" : txtRAStartIndex.Text.Trim()) + ":
";
            if (raReturn.Subscribers.Length > 0)
            {
                foreach (EmailResult email in raReturn.Subscribers)
                    lblResult.Text += "-- " + email.Email + "
";
            }
            else
            {
                lblResult.Text = "no subscribers found";
            }