Working with the Campaign Monitor API: Retrieving A List of Subscribers with PHP

I’ve used Campaign Monitor for years as an email marketing tool.  Recently, I had to work with PHP and the Campaign Monitor API to retrieve the  subscribers from an email list for a specific client.  Luckily, Campaign Monitor has made their API incredibly easy to work with while trying to accomplish some of these tasks and we are going to dive into how I accomplished it.

My objective was to retrieve a list of subscribers from an account, detect the total amount of subscribers on that list, and hide or show a sign up form based on whether the threshold of maximum subscribers was met.

Step 1: Using an API Wrapper Library

There are a multitude of languages and API Wrappers you can use to query and update the Campaign Monitor API, but since the site I was implementing this on was PHP, that is the language we will be using today.

You can explore their entire Campaign Monitor API PHP Library called createsend here.  You will need to include this library in your project in order to execute a lot of the tasks needed to work with your Campaign Monitor account.  I downloaded the library and included it in my WordPress theme template.  There are many other ways to include it and you can explore their documentation on how to do so.

Step 2: Get an API Key

Like many APIs, you will need authentication to work with them.  I found that most tasks for viewing and retrieving data only required the simpler API key so that’s the route we will be going today.  In order to manipulate the accounts data (like adding a new email to a list), you will likely need OAuth credentials.  For today’s example, we are looking to just retrieve the list of subscribers.  Let’s get an API Key!

Log into your Campaign Monitor account.  Go to Account Settings and then click on API Keys on the right hand side.  That should bring you to a page like this:

This has the list of all of your clients, their API keys, and some options to edit them.  It also has an Administrator API key, although, it is not recommended to use this when working on one specific client.  You are going to want to find your client and get their API Key.

Note: This is also how you find the Client ID.  In  some cases, you will need this info as well, but not for this example.

Step 3: Get a List ID

The second part you will need is the List ID.  When working with specific list of subscribers, you will need to find the specific List ID which identifies the group you want to work with.

In order to find your list ID, go to the Client you are working with, click on Lists & Subscribers, click on the list you would like to work with, and hit Change Name/Type.

Though you aren’t seeking to change the name, this will provide the API List ID that you are looking for.  It appears at the bottom of the settings like below:

Copy and save that List ID value.

Step 4: Prepare your Library and Code

As I mentioned before, this example pertains to obtaining a list of subscribers, figuring out how many there are, and showing a form whether or not we have exceeded that threshold.  It is in WordPress, so you would want to place the createsend library in your theme directory and call it like such:

<?php 
get_template_part('createsend/csrest_lists'); 
$auth = array('api_key' => '### YOUR API KEY GOES HERE ###'); 
?>

If you weren’t using WordPress, you would just use the standard PHP function:

<?php 
require_once('createsend/csrest_lists.php'); 
$auth = array('api_key' => '### YOUR API KEY GOES HERE ###'); 
?>

This, of course, is all relative to where you place your library, how you place your library, etc…. but the important thing is you are including it and establishing your API key by placing it where I have specified in the code.

Step 5: Use the Library to Call Active Subscribers from A List

Now the fun stuff.  Below is a code snippet to request the active subscribers from a list you specify:

<?php 
//SPECIFY THE LIST
$wrap = new CS_REST_Lists('##### YOUR LIST ID GOES HERE #####', $auth);

//REQUEST THE SUBSCRIBERS FROM THAT LIST
$result = $wrap->get_active_subscribers('', 1, 500, '', '', true);
//ARGUMENTS FOR get_active_subscribers ARE: 
//  "added since", "page number", "page size", "order by", "order", "consent to track"
                 
if($result->was_successful()) {
	$response = $result->response;
	$k = $response->TotalNumberOfRecords;
	if($k < 500) {
	   //WE HAVE NOT HIT 500 SUBSCRIBERS, SO SHOW THE FORM HERE
	} else {
	   //WE HAVE HIT 500 SUBSCRIBERS, HIDE FORM
	}
} else {
	echo 'Failed with code '.$result->http_status_code."\n<br /><pre>";
	var_dump($result->response);
	echo '</pre>';
}

?>

Ok, this is a big chunk, so let’s break down what’s happening here.

First, you are specifying the wrapper by identifying the list you want to query.  You got the List ID as explained earlier.

$wrap = new CS_REST_Lists('##### YOUR LIST ID GOES HERE #####', $auth);

Next, we are using the function get_active_subscribers  from your library to request them from your list how you see fit.  It takes several arguments, so it’s very important to plan and determine how those subscribers should be queried.  I placed the arguments in the comments below and the createsend documentation has a great amount of further explanation on this.  As an example, I didn’t set a time limit, I wanted the first 1-500, ordered by email, and ascending.  The Consent to Track is dependent on your list settings.

$result = $wrap->get_active_subscribers('', 1, 500, 'email', 'asc', true); 
//ARGUMENTS FOR get_active_subscribers ARE: 
// "added since", "page number", "page size", "order by", "order", "consent to track"

After we query that list, we are asking: Was this successful?  If so, let’s store the response as a variable, determine how many active subscribers we got, and if it’s above 500 (an arbitrary number for the sake of example), then hide the form!  If not, show the form!

For some purposes, you will want to loop through the result to list names, emails, etc.  Everything stored in the $response  variable will have what you need!  You can iterate through the array like so:

var_dump($response);

Conclusion and Full Code Snippet

<?php 
get_template_part('createsend/csrest_lists'); 
$auth = array('api_key' => '### YOUR API KEY GOES HERE ###');
$wrap = new CS_REST_Lists('##### YOUR LIST ID GOES HERE #####', $auth);
$result = $wrap->get_active_subscribers('', 1, 500, '', '', true);
            
if($result->was_successful()) {
	$response = $result->response;
	$k = $response->TotalNumberOfRecords;
	if($k < 500) {
	   //WE HAVE NOT HIT 500 SUBSCRIBERS, SO SHOW THE FORM HERE
	} else {
	   //WE HAVE HIT 500 SUBSCRIBERS, HIDE FORM
	}
} else {
	echo 'Failed with code '.$result->http_status_code."\n<br /><pre>";
	var_dump($result->response);
	echo '</pre>';
}
?>

The Campaign Monitor API is very robust, regardless of what language or method you are using to work with it. Hopefully, this example served as a helpful tool in working with your Campaign Monitor clients and you can help build upon this example for your needs.  Happy Coding!

Leave A Comment

Your email address will not be published. Required fields are marked *