Enabling SMS subscriptions to your MailChimp list using Plivo, Part 1

I use MailChimp to power the mailing list on this site. It’s a great service has been my go-to for years. One of the greatest features about MailChimp is it’s API which lets you integrate your list into all kinds of services. For my site, given the theme, I wanted to integrate the mailing list with a phone application. Over the next few posts I’m going to show how I created my MailChimp phone application that lets someone subscribe to my list by texting me their email address as well as a few other cool features that are less practical, but still neat.

I can think of several useful applications of this script so I decided to release it to anyone that want it.  Next time you’re out and about and meet someone that wants to subscribe to your list you can just tell them “text me your email” instead of, “go to my website, click on newsletter, fill out the form, and then check your email for the confirmation.”

Much cooler and way more natural.

Getting started with Plivo

If you’re not familiar with Plivo, it’s a service which allows you to interact with the phone system using a really powerful API. Similar to Twilio, but much better in my opinion. If you don’t have an account you can get a free developer account without a credit card at http://www.plivo.com.

Getting a MailChimp API Key

You’ll also need a MailChimp API key and the numeric List ID for the list you want to subscribe your callers to.  You can create an API key in MailChimp under “My Account” -> “Extras”

resourceThe List ID is a little tougher to find, but if you navigate to the list and click the “Settings” dropdown you will find the List ID.


The Plivo app

I built the Plivo message app in PHP because it’s widespread enough for anyone to figure out. This app is simple enough, feel free to use any language you prefer, I’ll use the official Plivo helper library and a really simple MailChimp API wrapper from Drew McLellan.

Anatomy of a Plivo SMS message

When Plivo receives an SMS it makes a simple POST request to your “Message url”, which we will define a little later when we setup our Plivo application and add our number, it expects the script to return an XML document with a <Response> element. Plivo has a really straight forward PHP library that we’ll use to create the XML, so all we need to do is capture the data from the POST and do something with it. The full description is at https://plivo.com/docs/xml/request/ If you want to understand the whole process.

Here’s the first block of code which will load the Plivo and MailChimp libraries and assign the variables sent by Plivo.


//Collect the details from the SMS
$to = $_REQUEST['To'];
$from = $_REQUEST['From'];
$text = $_REQUEST['Text'];

So now that we have our variables set, let’s check to see if the body of the SMS is a valid email address and if so subscribe them to my MailChimp list.

The contents of the SMS will be in the $text variable. For now I’m just going to validate this variable using the php filter_var function. This will do a basic evaluation on the string to make sure it follows the general email address rules, it doesn’t actually verify that the email is valid, but we just want to make sure they sent us something that looks like an email that we’ll pass on the MailChimp.

if (filter_var($text, FILTER_VALIDATE_EMAIL)) { 
   ## Subscribe the caller
   $MailChimp = new MailChimp('API_KEY');
   $result = $MailChimp->call( 'lists/subscribe', 
				array('id' => 'LIST ID', 'email' => array('email'=> $text)));

Next we’ll make sure the MailChimp API Call worked and respond to the SMS with a confirmation.

        if ($result){
                 $body = "Thanks! Check your email to confirm your subscription";
}else{ //Email didn't Validate
        $body = "Sorry, that does not look like a valid email";
//Setup the Plivo Response      
$r = new Response();
header('Content-type: application/xml');
echo $r->toXML();

That’s really all there is to the basic script. Because my mailing list on MailChimp is setup to “Double Opt-In” the email address will get a confirmation link to click on. This makes sure that the email is valid because we really didn’t do any validation except check the format.  Now that we’ve got the script which will answer our incoming SMS we need to create a Plivo application and tell it to use this script.

Create the Plivo application

First, login to plivo.com. From the Applications tab, create a new application and give it a name.  The only thing you need to change from the default is the “Message url.” We’ll put the URL to the script we just created and make sure the method is POST.


Now that the application has been created we’ll add a phone number. From the Numbers section, click on Buy Number and find a number you like, just make sure you check SMS Enabled.  Unfortunately you can only pick the area code and a random number will be assigned, but you can always drop the number and try again if you get one you don’t like.

resource 2

Once you select an area code, just make sure to assign the number to the application you just created.


That’s all there is to it.  Now just tell people to text you their email and they’re subscribed to your MailChimp list!

Want to see it in action? just text your email to (779) 201-1688 and I’ll notify you once the next part of this tutorial is posted.

You can download the complete code and libraries here if you want.

Next Steps…

Check back next week for part two. In part two we’ll add some more interactivity, expand our application to handle more complex messages, and show you how to integrate more meta-data to the list like tracking the phone number and caller ID name in your MailChimp List. I’ll also show you how to let your subscribers opt-in for SMS notifications when you send updates to your list.

As always, if you’re interested in learning how to build voice and SMS powered applications, check out Building Phone Applications or of course you could just text me your email at 779-201-1688 and I’ll send you some more applications.

Update 2/3/2014: Part 2 is now posted here: Enabling SMS subscriptions to your MailChimp list using Plivo, Part 2

You may also like...