api.eConnectEmail.com
   Interacting with the eConnect Email's API

GetListDetails()

Retrieve detailed information about a contact list, including custom field definitions.

Parameters

ApiKey (Required)
    Your application authentication key. Click here to find out more.
ListID (Required)
    The ID number of the list whose details you want to retrieve. You can get list IDs from the GetLists method, or from the Contact Lists tab in the main application. Click here to find out more.

Return Value

On success, this method returns the following information:

• Name - the list name
• Owner Name - the name of the list's owner
• Owner Email - the email address of the list's owner
• Notify Owner? - 1 if the list owner is notified of subscribe and unsubscribe requests; otherwise, 0
• Reply-to Email - the default "reply-to" email address used when sending email campaigns to the list
• Subscriber Count - the current number of active subscribers in the list
• Unsubscribe Count - the current number of subscribers with "unsubscribe" status, i.e. those who have chosen to no longer receive email from the list
• Bounced Count - the current number of subscribers with "bounced" status; this includes only "hard" bounces (such as those whose mailbox no longer exists, or who soft-bounced five or more times)
• Date Created - the specific date and time the list was created, in ISO 8601 format, YYYY-MM-DDThh:mm:ss.sTZD (example: 1997-08-31T00:23:45.00+00:00, or August 31, 1997 12:23am GMT+0). Note: the original 2.0 version of the API used the format YYYY-MM-DD, but that version and all newer ones have been updated to use the more exact ISO 8601 format.
• Custom Fields - an array listing the custom fields defined for this list. Each custom field contains the following information:
      Field ID - the ID number of the field, as seen in under the Contact Lists tab; click here for more information
      Name - the internal name of the custom field
      Type - the field type of the custom field (text (one-line), textarea (multiline), date, number, dropdown, checkbox, radiobutton, etc.)
      Default Value - if applicable, the value placed in the field by default (i.e. if a value is not explicitly provided)
      Is Required? - 1 if the custom field must be filled in, 0 if optional

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

Usage Notes

none

Fault Codes

100 - Invalid API Key
    The API key is not valid or expired
200 - Invalid List ID
    The List ID is invalid.

SOAP Sample Request

    
    
        
            
                STRING
                INT
            
        
    

SOAP Sample Response

    
    
        
            
                STRING
                STRING
                STRING
                STRING
                INT
                INT
                INT
                INT
                STRING
                
                    <item>
                        <FieldID>INT</FieldID>
                        <Name>STRING</Name>
                        <Type>STRING</Type>
                        <DefaultValue>STRING</DefaultValue>
                        <IsRequired>INT</IsRequired>
                    </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->GetListDetails(LIST_ID);

// 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
            ListParams gldParams = new ListParams();
            gldParams.ApiKey = txtApiKey.Text;
            gldParams.ListID = int.Parse(txtGLDListID.Text);

            // Invoke method and store result
            ReturnListDetails listDetails = api.GetListDetails(gldParams);

            // Display results
            lblResult.Text = FormatValue("List Name", listDetails.Name)
                + FormatValue("Owner Name", listDetails.OwnerName)
                + FormatValue("Owner Email", listDetails.OwnerEmail)
                + FormatValue("Notify Owner?", (listDetails.NotifyOwner == 1 ? "Yes" : "No"))
                + FormatValue("Reply-To Email", listDetails.ReplyToEmail)
                + FormatValue("Subscribers", listDetails.SubscriberCount.ToString())
                + FormatValue("Unsubscribed", listDetails.UnsubscribeCount.ToString())
                + FormatValue("Bounced", listDetails.BouncedCount.ToString())
                + FormatValue("DateCreated", listDetails.DateCreated);
            lblResult.Text += "
Custom Fields:
";
            foreach (ReturnListCustomFields customField in listDetails.CustomFields)
            {
                lblResult.Text += "
" + customField.Name + " (ID " + customField.FieldID.ToString() + ", " + customField.Type + ")"
                    + (customField.IsRequired == 1 ? " - required" : "")
                    + (customField.DefaultValue != "" ? " - default=" + customField.DefaultValue : "") + "
";
            }
            lblResult.Text += "
";