Developers

Example Usage of
list_list

View multiple mailing lists.

Description: View multiple mailing lists in the system, including all information associated with each.
Endpoint: /admin/api.php?api_action=list_list
HTTP method: GET
Supported output formats: xml, json, serialize
Requires authentication: true
Parameters:
* indicates requirement. Underlined params include in URL, otherwise as part of the post body. POST data must be formatted as
Content-Type: application/x-www-form-urlencoded
. We don't accept any other input formats like JSON.
Variable Description
api_action*list_list
api_key*Your API key
api_outputxml, json, or serialize (default is XML)
ids*A comma-separated list of subscription form ID's of lists you wish to view. Pass "all" to view all lists.
filters[name]Filter: Perform a pattern match (LIKE) for List Name.
global_fieldsWhether or not to include global custom fields. (set to 1 for yes, and 0 for no)
fullWhether or not to return ALL data, or an abbreviated portion (set to 1 for ALL data, and 0 for abbreviated).
Example response:
Variable Description
0Array
idID of the list. Example: 1
stringidURL-friendly name of list. Example: general-list
useridUser ID who created this list. Example: 1
nameInternal name of list. Example: General List
cdateDate/time the list was created. Example: 2011-03-02 14:46:40
p_use_tracking1
p_use_twitterWhether or not to use Twitter campaign auto-sharing. Examples: yes = 1, no = 0
p_use_facebookWhether or not to use Facebook campaign auto-sharing. Examples: yes = 1, no = 0
p_embed_imageWhether or not to embed images for campaigns send to this list. Examples: yes = 1, no = 0
p_use_captchaWhether or not to use captcha image verification when subscribing to this list. Examples: yes = 1, no = 0
send_last_broadcastWhether or not to send last broadcast message to new contacts of this list. Examples: yes = 1, no = 0
privateWhether or not this list is private (not visible on public side). Examples: yes = 1, no = 0
twitter_tokenThe Twitter token used to send updates to your Twitter account.
twitter_token_secretThe Twitter token secret used to send updates to your Twitter account.
facebook_sessionThe Facebook session used to send updates to your Facebook account.
carboncopyAdditional email addresses that campaigns for this list are sent to.
subscription_notifyWhenever a contact subscribes to this list, an email gets sent to this address.
unsubscription_notifyWhenever a contact UNsubscribes to this list, an email gets sent to this address.
require_nameWhether or not to require a name when subscribing to this list. Examples: yes = 1, no = 0
get_unsubscribe_reasonWhether or not to ask for a reason when contacts UNsubscribe. Examples: yes = 1, no = 0
to_nameDefault contact name (used when contact has not entered a name). Example: Recipient
optinoptout1
sender_nameSender's Contact Information.
sender_addr1Sender's Contact Information.
sender_addr2Sender's Contact Information.
sender_citySender's Contact Information.
sender_stateSender's Contact Information.
sender_zipSender's Contact Information.
sender_countrySender's Contact Information.
sender_phoneSender's Contact Information.
sender_urlSender's Contact Information.
sender_reminderSender's Reminder to Contacts.
listidID of the list. Example: 1
subscriber_countNumber of active Contacts in the list.
p_admin1
p_list_addPermission for adding lists. Example: 1 = yes, 0 = no
p_list_editPermission for editing lists. Example: 1 = yes, 0 = no
p_list_deletePermission for deleting lists. Example: 1 = yes, 0 = no
p_list_syncPermission for accessing database sync. Example: 1 = yes, 0 = no
p_list_filterPermission for accessing list segments. Example: 1 = yes, 0 = no
p_message_addPermission for adding messages. Example: 1 = yes, 0 = no
p_message_editPermission for editing messages. Example: 1 = yes, 0 = no
p_message_deletePermission for deleting messages. Example: 1 = yes, 0 = no
p_message_sendPermission for sending messages. Example: 1 = yes, 0 = no
p_subscriber_addPermission for adding contacts. Example: 1 = yes, 0 = no
p_subscriber_editPermission for editing contacts. Example: 1 = yes, 0 = no
p_subscriber_deletePermission for deleting contacts. Example: 1 = yes, 0 = no
p_subscriber_importPermission for importing contacts. Example: 1 = yes, 0 = no
p_subscriber_approvePermission for approving contacts. Example: 1 = yes, 0 = no
fieldsArray
groupsArray
groupsCnt2
optidThe Opt Set ID. Example: 1
optnameInternal name of the email confirmation set. Example: Default Email Confirmation Set
optin_confirmWhether or not Opt-in confirmation is being used. Examples: yes = 1, no = 0
optin_formatFormat of Opt-in confirmation email. Example: mime
optin_from_nameFrom Name for Opt-in confirmation email. Example: ActiveCampaign Email Marketing
optin_from_emailFrom Email for Opt-in confirmation email. Example: email@test.com
optin_subjectSubject for Opt-in confirmation email. Example: Please confirm your subscription
optin_textText of Opt-in confirmation email. Example: Thank you for subscribing.
optin_htmlHTML of Opt-in confirmation email. Example: <body><div style="font-size: 12px; font-family: Arial, Helvetica;"><strong>Thank you for subscribing to %LISTNAME%!</strong></div> <div style="padding: 15px; font-size: 12px; background: #F2FFD8; border: 3px solid #E4F4C3; margin-bottom: 0px; margin-top: 15px; font-family: Arial, Helvetica;">To confirm that you wish to be subscribed, please click the link below:<br /><br /><a href="%CONFIRMLINK%"><strong>Confirm My Subscription</strong></a></div><p> </p></body>
optout_confirmWhether or not Opt-out confirmation is being used. Examples: yes = 1, no = 0
optout_formatFormat of Opt-out confirmation email. Example: mime
optout_from_nameFrom Name for Opt-out confirmation email. Example: ActiveCampaign Email Marketing
optout_from_emailFrom Email for Opt-out confirmation email. Example: email@test.com
optout_subjectSubject for Opt-out confirmation email. Example: Please confirm your unsubscription
optout_textText of Opt-out confirmation email. Example: Please click this link to confirm your unsubscription: %CONFIRMLINK%
optout_htmlHTML of Opt-in confirmation email. Example: Please click this link to confirm your unsubscription:<br /><a href="%CONFIRMLINK%">%CONFIRMLINK%</a>
bouncesArray
facebook_oauth_meArray
facebook_oauth_logout_urlURL to log-out of Facebook session.
facebook_oauth_login_urlURL to log-in to Facebook session.
result_codeWhether or not the response was successful. Examples: 1 = yes, 0 = no
result_messageA custom message that appears explaining what happened. Example: Something is returned
result_outputThe result output used. Example: serialize

PHP Example

This is an example of using the list_list call with PHP. You can replicate the same idea in virtually any other programming language. The example shown is using serialize as the output format. You can change that to XML or JSON if you would like.

<?php

// By default, this sample code is designed to get the result from your ActiveCampaign installation and print out the result
$url = 'http://account.api-us1.com';


$params = array(

	// the API Key can be found on the "Your Settings" page under the "API" tab.
	// replace this with your API Key
	'api_key'      => 'YOUR_API_KEY',

	// this is the action that fetches a list info based on the ID you provide
	'api_action'   => 'list_list',

	// define the type of output you wish to get back
	// possible values:
	// - 'xml'  :      you have to write your own XML parser
	// - 'json' :      data is returned in JSON format and can be decoded with
	//                 json_decode() function (included in PHP since 5.2.0)
	// - 'serialize' : data is returned in a serialized format and can be decoded with
	//                 a native unserialize() function
	'api_output'   => 'serialize',

	// a comma-separated list of IDs of lists you wish to fetch
	'ids'          => '1,2,3,4,5',

	// filters: supply filters that will narrow down the results
	//'filters[name]'      => 'General',  // perform a pattern match (LIKE) for List Name

	// include global custom fields? by default, it does not
	//'global_fields'      => true,

	// whether or not to return ALL data, or an abbreviated portion (set to 0 for abbreviated)
	'full'         => 1,
);

// This section takes the input fields and converts them to the proper format
$query = "";
foreach( $params as $key => $value ) $query .= urlencode($key) . '=' . urlencode($value) . '&';
$query = rtrim($query, '& ');

// clean up the url
$url = rtrim($url, '/ ');

// This sample code uses the CURL library for php to establish a connection,
// submit your request, and show (print out) the response.
if ( !function_exists('curl_init') ) die('CURL not supported. (introduced in PHP 4.0.2)');

// If JSON is used, check if json_decode is present (PHP 5.2.0+)
if ( $params['api_output'] == 'json' && !function_exists('json_decode') ) {
	die('JSON not supported. (introduced in PHP 5.2.0)');
}

// define a final API request - GET
$api = $url . '/admin/api.php?' . $query;

$request = curl_init($api); // initiate curl object
curl_setopt($request, CURLOPT_HEADER, 0); // set to 0 to eliminate header info from response
curl_setopt($request, CURLOPT_RETURNTRANSFER, 1); // Returns response data instead of TRUE(1)
//curl_setopt($request, CURLOPT_SSL_VERIFYPEER, FALSE); // uncomment if you get no gateway response and are using HTTPS
curl_setopt($request, CURLOPT_FOLLOWLOCATION, true);

$response = (string)curl_exec($request); // execute curl fetch and store results in $response

// additional options may be required depending upon your server configuration
// you can find documentation on curl options at http://www.php.net/curl_setopt
curl_close($request); // close curl object

if ( !$response ) {
	die('Nothing was returned. Do you have a connection to Email Marketing server?');
}

// This line takes the response and breaks it into an array using:
// JSON decoder
//$result = json_decode($response);
// unserializer
$result = unserialize($response);
// XML parser...
// ...

// Result info that is always returned
echo 'Result: ' . ( $result['result_code'] ? 'SUCCESS' : 'FAILED' ) . '<br />';
echo 'Message: ' . $result['result_message'] . '<br />';

// The entire result printed out
echo 'The entire result printed out:<br />';
echo '<pre>';
print_r($result);
echo '</pre>';

// Raw response printed out
echo 'Raw response printed out:<br />';
echo '<pre>';
print_r($response);
echo '</pre>';

// API URL that returned the result
echo 'API URL that returned the result:<br />';
echo $api;?>

Questions? Discuss this API call in our developer forum