lists – v1.3

 lists(string apikey, array filters, int start, int limit)

Retrieve all of the lists defined for your user account

Section
List Related

Parameters
apikey	a valid API Key for your user account. Get by visiting your API dashboard
filters	a hash of filters to apply to this query - all are optional: string list_id optional - return a single list using a known list_id. Accepts multiples separated by commas when not using exact matching string list_name optional - only lists that match this name string from_name optional - only lists that have a default from name matching this string from_email optional - only lists that have a default from email matching this string from_subject optional - only lists that have a default from email matching this string created_before optional - only show lists that were created before this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr) string created_after optional - only show lists that were created since this date/time (in GMT) - format is YYYY-MM-DD HH:mm:ss (24hr) boolean exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values - defaults to true
start	optional - control paging of lists, start results at this list #, defaults to 1st page of data (page 0)
limit	optional - control paging of lists, number of lists to return with each call, defaults to 25 (max=100)

Returns

array

an array with keys listed in Returned Fields below int total the total number of lists which matched the provided filters array data the lists which matched the provided filters, including the following for string id The list id for this list. This will be used for all other list management functions. int web_id The list id used in our web app, allows you to create a link directly to it string name The name of the list. string date_created The date that this list was created. boolean email_type_option Whether or not the List supports multiple formats for emails or just HTML boolean use_awesomebar Whether or not campaigns for this list use the Awesome Bar in archives by default string default_from_name Default From Name for campaigns using this list string default_from_email Default From Email for campaigns using this list string default_subject Default Subject Line for campaigns using this list string default_language Default Language for this list's forms int list_rating An auto-generated activity score for the list (0 - 5) string subscribe_url_short Our eepurl shortened version of this list's subscribe form (will not change) string subscribe_url_long The full version of this list's subscribe form (host will vary) string beamer_address The email address to use for this list's Email Beamer array stats various stats and counts for the list - many of these are cached for at least 5 minutes int member_count The number of active members in the given list. int unsubscribe_count The number of members who have unsubscribed from the given list. int cleaned_count The number of members cleaned from the given list. int member_count_since_send The number of active members in the given list since the last campaign was sent int unsubscribe_count_since_send The number of members who have unsubscribed from the given list since the last campaign was sent int cleaned_count_since_send The number of members cleaned from the given list since the last campaign was sent int campaign_count The number of campaigns in any status that use this list int grouping_count The number of Interest Groupings for this list int group_count The number of Interest Groups (regardless of grouping) for this list int merge_var_count The number of merge vars for this list (not including the required EMAIL one) int avg_sub_rate the average number of subscribe per month for the list (empty value if we haven't calculated this yet) int avg_unsub_rate the average number of unsubscribe per month for the list (empty value if we haven't calculated this yet) int target_sub_rate the target subscription rate for the list to keep it growing (empty value if we haven't calculated this yet) int open_rate the average open rate per campaign for the list (empty value if we haven't calculated this yet) int click_rate the average click rate per campaign for the list (empty value if we haven't calculated this yet) array modules Any list specific modules installed for this list (example is SocialPro)

Examples (2)

download example code

[1] mcapi_lists.php

<?php
/**
This Example shows how to pull the Members of a List using the MCAPI.php 
class and do some basic error checking.
**/
require_once 'inc/MCAPI.class.php';
require_once 'inc/config.inc.php'; //contains apikey
 
$api = new MCAPI($apikey);
 
$retval = $api->lists();
 
if ($api->errorCode){
	echo "Unable to load lists()!";
	echo "\n\tCode=".$api->errorCode;
	echo "\n\tMsg=".$api->errorMessage."\n";
} else {
	echo "Lists that matched:".$retval['total']."\n";
	echo "Lists returned:".sizeof($retval['data'])."\n";
	foreach ($retval['data'] as $list){
		echo "Id = ".$list['id']." - ".$list['name']."\n";
		echo "Web_id = ".$list['web_id']."\n";
		echo "\tSub = ".$list['stats']['member_count'];
		echo "\tUnsub=".$list['stats']['unsubscribe_count'];
		echo "\tCleaned=".$list['stats']['cleaned_count']."\n";
	}
}
 
?>
 

[2] xml-rpc_lists.php

<?php
/**
This Example shows how to use XML-RPC to Retrieve all of the Lists on your
account and display some info about them.
Note that we are using the PEAR XML-RPC client and recommend others do as well.
**/
require_once 'XML/RPC2/Client.php';
require_once 'inc/config.inc.php';
try {
    $client = XML_RPC2_Client::create($apiUrl);
 
	$lists = $client->lists($apikey);
	echo "SUCCESS!\n";
	foreach ($lists as $list){
		echo "Id = ".$list['id']." - ".$list['name']."\n";
	}
} catch (XML_RPC2_FaultException $e){
	echo "ERROR!!!!\n";
	echo $e->getFaultCode()." : ".$e->getFaultString()."\n";
}
?>