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.1
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 <head> 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 populated2:
<?php
echo '<select id="Field109" name="Field109" class="field select medium" tabindex="3">';
foreach($fields["anyType"]['ListCustomField']['1']['FieldOptions']['1']['string'] as $key => $value) {
echo "<option value=\"$value\">$value</option>";
}
echo "</select>";
?>
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 "<strong>Sorry, the email address <em>$email_out</em> is already in the database!</strong>";
echo '
';
echo 'Click <a href="/signup.php" title="Add a New User">here</a> 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 <strong>$name</strong> with the email address <strong>$email_out</strong> to the database.";
echo "
$ref
";
echo 'Click <a href="/signup.php" title="Add a New User">here</a> 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 ?>
<iframe height="739" allowTransparency="true" frameborder="0" scrolling="no" style="width:100%;border:none" src="http://domain.com/api/signup.php">></iframe>
<?php }
elseif (is_page('414')) { // Devonport ?>
<iframe height="739" allowTransparency="true" frameborder="0" scrolling="no" style="width:100%;border:none" src="http://domain.com/api/signup2.php">></iframe>
<?php }
}
add_action('thesis_hook_after_post','email_forms');
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. ↩
{ 1 trackback }
{ 3 comments… read them below or add one }
Great info! I came upon a problem when an inactive subscriber exists (as unsubscribed or deleted) on a subscriber list. The signup form accepts the entry, however the subscriber remains listed as unsubscribed or deleted instead of becoming active.
What’s the best approach to check the list for existing inactive subscribers and reactivate them?
Steve: That’s a great question. The current code doesn’t deal particularly well with unsubscribed users as the submission end—because they’re sitting in the CampaignMonitor blacklist they won’t be resubscribed, but the user is told they have been.
We’re planning on building in a check to see if the user is on the unsubscribe list, so I’ll post that up when it gets done. Might just help you solve your problem!
Hi Mitch.
I loved the idea of this script to check if a person is subscribed to a list and then warns if they are already on it. however i can’t seem to get it to work. It submits the form ok and add a subscriber no problem, but it doesn’t bring up a error or warning if the email is already in the system.
Your thoughts would be gratefully appreciated.