Jump to content

GetSubscriber()

Retrieve a subscriber's information, including all custom field data.

Parameters

ApiKey (Required)
    Your application authentication key. Click here to find out more.
ListID (Required)
    The ID number of the list to which the subscriber belongs. Click here to find out more.
Email (Required)
    The email address of the subscriber you would like to retrieve.

Return Value

On success, this method returns the following information:

  • Email - the subscriber's email address
  • List ID - the ID number of the requested list (i.e. this will match the provided ListID parameter)
  • Confirmed - a number indicating whether the subscriber's email address has been confirmed (1) or not yet confirmed (0)
  • Bounced - a number indicating whether the subscriber has a "bounced" status (1) or not (0) - a "bounced" staus means an e-mail to the subscriber has hard-bounced (a fatal error such as unknown email address), or soft-bounced at least five times (due to reasons such as mailbox full)
  • Unsubscribed - a number indicating whether the subscriber has unsubscribed from the list (1) or not (0)
  • Date Subscribed - the specific date and time the subscriber joined the list, in ISO 8601 format, YYYY-MM-DDThh:mm:ss.sTZD (example: 2012-12-21T11:11:00.00-04:00, or December 21, 2012 11:11am Eastern Time).
  • Custom Fields - an array listing the custom field values for the subscriber. Each custom field contains the following information:
        Field ID - the ID number of the custom field, as seen in under the Contact Lists tab; you can get custom field information via the GetListDetails method; click here for more information on custom fields
        Value - the value of the custom field assigned to the subscriber.  Note: checkbox (i.e. multi-select) fields will list multiple values together in one comma-delimited list of values, each surrounded by double-quotes

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

Usage Notes

For most field types which store basic, single-value data, values will come back as a basic string. But please note that the following field types return data in special ways:

  • Checkbox (i.e. multi-select) fields - provide mutiple values, each within double quotes, and separated by commas; the data is returned in this same format via GetSubscriber (this is a change from version 1 of the API, where data had to be provided in a cumbersome format)
  • Date fields - dates must be provided in YYYY-MM-DD format

Fault Codes

1 - Invalid Email Address
    The email value is malformed or invalid
3 - Subscriber Does Not Exist
    The email does not exist in the specified list. Unsubscribed and Bounced subscribers will still be available from this methoud.
100 - Invalid API Key
    The API key is not valid or expired
200 - Invalid ListID
    The Associated List is not valid

SOAP Sample Request


    
    
        
            
                STRING
                INT
                STRING

SOAP Sample Response


    
    
        
            
                STRING
                INT
                INT
                INT
                INT
                
                    <item>
                        <FieldID>INT</FieldID>
                        <Value>STRING</Value>
                    </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->GetSubscriber(LIST_ID, 'EMAIL_ADDRESS');
// 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
            EmailParams emailParams = new EmailParams();
            emailParams.ApiKey = txtApiKey.Text;
            emailParams.ListID = int.Parse(txtGetSubListID.Text);
            emailParams.Email = txtGetSubEmail.Text;

            // Invoke method and store result
            ReturnSubscriber subscriber = api.GetSubscriber(emailParams);

            // Display results
            lblResult.Text = "";
            lblResult.Text += FormatValue("Email", subscriber.Email);
            lblResult.Text += FormatValue("ListID", subscriber.ListID.ToString());
            lblResult.Text += FormatValue("Confirmed", subscriber.Confirmed.ToString());
            lblResult.Text += FormatValue("Bounced", subscriber.Bounced.ToString());
            lblResult.Text += FormatValue("Unsubscribed", subscriber.Unsubscribed.ToString());
            lblResult.Text += "Custom Fields:
";
            if (subscriber.CustomFields.Length > 0)
            {
                foreach (CustomFieldsResult custField in subscriber.CustomFields)
                    lblResult.Text += FormatValue("Custom Field[" + custField.FieldID + "]", custField.Value);
            }
            else
            {
                lblResult.Text = "no custom fields present.";
            }