Improved Subscriber Management with the Campaign Monitor API

Mitch Cooper — Tue, 07 Apr 2009 06:46:18 +0000

For many of our clients, an integral part of maximising their web presence is through effectively leveraging email marketing as a medium for promoting their brand and products. While simple Feedburner email is a great solution for giving your readership a means to receive your updates in their inbox, if you really want to make an impact with email you can’t look past CampaignMonitor.

Subscriber Management with the CampaignMonitor API

With it’s designer focussed approach, powerful and elegant analytics and can’t-be-bet client publishing tools we’ve found CampaignMonitor was perfect out of the box for just about everything. Recently however we faced a scenario where CampaignMonitor’s ’simple, yet effective’ subscriber management process wasn’t quite enough: in step the powerful CampaignMonitor API.

We had a client who needed a customized valediction line, signing the email off according to who referred the client to the database. This was super easy to achieve using CampaignMonitor’s custom fields, but there was a fair bit of a juggling involved in ensuring we never overwrote the initial referring agent in the database in the event someone else landed the same referral.

Creating the Sign-up Form

To overcome this, we first built our sign-up form. Because we’re lazy we truly believe forms should be fun we headed straight over to Wufoo.com and put together the form. Utilizing Wufoo’s awesome export code function, we had a beautiful form together in no time. The ingredients: name, email address, referring agent in a drop down box and a tick box asking agent’s to confirm they’d received explicit permission to add their client.¹

You’ll want to paste this into a new PHP file – call it signup.php

Accessing the API

To access the API, we grabbed the sweet CampaignMonitor PHP API wrapper from here.

You’ll want extract CMBase.php to the folder where you’ve placed signup.php and paste the following right after the tag in the signup form file:


$api_key = 'YourCampaignMonitorAPIKey';
$client_id = 'YourClientsClientID';
$campaign_id = null;
$list_id = 'TheIDofTheListYouWantToChange';
$cm = new CampaignMonitor( $api_key, $client_id, $campaign_id, $list_id );

Populating the Drop Down with Custom Fields

You can ignore the formatting details in the code below and you’ll likely need to amend exactly what you’re trying to output in the drop down, but this code should serve as an workable starting point to get that drop down populated²:


';
 foreach($fields["anyType"]['ListCustomField']['1']['FieldOptions']['1']['string'] as $key => $value) {
 echo "";
 }
 echo "";
?>

You’ll also want to note down the name so we can grab the details from the field to pass up to Campaign Monitor through the API.

Getting Ready to Work with the Subscriber Data

We’ve kept it simple in deploying this form and simple created a second PHP file called signup-submit.php which we’ll use to review the data submitted by the agent, let them know what happened and pass it up through the API if the subscriber does not exist.

You’ll want to create a similar file. You’ll need to include the API details as in signup.php and you’ll want to set the action of the previous form to send everything through to signup-submit.php.

You’ll want to grab the form data and set them as variables so we can work with them easily in PHP. Here’s what we’ve done:


$name = $_POST["Field1"];            // Name
$email_in = $_POST["Field2"];        // Raw email from form
$email_out = strtolower($email_in); // Strip emails to lower case
$ref = $_POST["Field109"];            // Referring Agent

Checking if the Subscriber Exists

You might’ve noticed above, that we’ve got a vairable for $email_in and $email_out. Our agent’s have a nasty habit of capitalising emails, so to keep everything tidy on our side of the equation, we’ve opted to strip the caps out of anything they submit. I don’t believe it’s necessary – but a handy trick, nonetheless!

So, with the email ready we’ll want to check through the API if it’s already registered. With the PHP wrapper it’s just a simple function away:


$var = $cm->subscribersGetIsSubscribed($email_out,$list_id);

Actioning the Results

If the subscriber is already registered we want to let the agent know and call it a day. Otherwise, we’ll want to get them subscribed quick smart. The API call we used in the previous step returns a value of true or false, depending on whether or not the subscriber exists. With this, we can simply use an if / else approach to adding subscribers. Here we go:

If the Subscriber Exists

This one’s pretty simple – if the subscriber exists and the variable $var returns true we’ll let the agent know and leave it that, providing a link so they can jump back and try another address if need be:


if ($var['anyType'] === 'True') {
 echo "Sorry, the email address $email_out is already in the database!";
 echo '

';
 echo 'Click here or use the back button in your browser to try a different subscriber.';
 }

If the Subscriber is New

If $var does not return true (the subscriber does not exist) we can go ahead and add the subscriber through the CampaignMonitor API:


else {
 // Add to Database with Custom Fields
 $result = $cm->subscriberAddWithCustomFields("$email_out","$name", array('ReferringAgent' => $ref,'SignatureImage' => $image));
 if($result['Result']['Code'] == 0) {
 echo "Success! You've added $name with the email address $email_out to the database.";
 echo "
$ref
";
 echo 'Click here or use the back button in your browser to try a different subscriber.';
 }
 else {
 echo 'Error : ' . $result['Result']['Message'];
 }
 }

You’ll need to change the field variables according to what you’ve used, but that should pretty much have you set. Drop us a comment if you have any trouble implementing this and we’ll see what we can do!

Bonus for the Thesis Framework

If you’re running on Thesis, as many of our subscribers are, getting your shiny new sign-up form into your site is as simple as hooking it in. We’ve got multiple sign-up forms on different pages for one client, so here’s how we hooked ‘em in:


/* Email Sign Up Forms */
function email_forms() {
 if (is_page('427')) {  // Albany ?>
 >
 
 >
 
Final Note
Just a big shout out to the folks over on the PHP Freaks forums and the CampaignMonitor support team who went well above the call of duty to help us nail this one quickly. Couldn’t have done this without ‘em!



We haven’t had any trouble with this so far, but we reckon as developers it’s crucial we take every opportunity to reinforce the importance of permission in permission based marketing. ↩
If all you’re looking to do is create a form that will check for duplicates you can skip this step. If you’re looking for a bit more in terms of custom fields, you can add as many of these as you like. Beauty. ↩

DIYNINJAS » CampaignMonitor