Using the MailChimp API

When it comes to marketing, there are many ways of gaining new business; Whether it’s via PPC campaigns, direct mail, social media etc…  One avenue that I feel is somewhat neglected is email marketing.

Email marketing provides a great way of keeping your existing customers engaged with useful content so that you can build a long-term relationship with them. These people are proven buyers of your product or service, and therefore certainly should not be ignored. If you do, you may be losing out on a lot of potential revenue.

The whole idea of email marketing may sound a little daunting at first as there’s a lot to consider. Some questions may be:

• How do you create and send out an email?
• Does your hosting company have hourly limits on outgoing email?
• How do you let people subscribe, but more importantly, unsubscribe?
• How do you measure the successfulness of your email campaigns?
• How do you check if your email appears correctly in different email clients?

MailChimp to the rescue!

MailChimp is an awesome tool for designing and sending email marketing campaigns, as well as building and managing your email list. Best of all it’s free if you have less than 2,000 subscribers and send less than 12,000 emails per month!

It has a whole range of functionality including but not limited to:

• A WYSIWYG editor with drag & drop functionality, which makes creating emails very easy even for users with no coding experience. They also have a wide range of premade templates you can use, or for the more advanced users, the ability to upload your own HTML and image assets.
• An easy way to integrate a sign up form to your website or your Facebook page.
• The ability to easily import from 3rd party websites such as Salesforce, Highrise, Eventbrite, Zoho, Zendesk, FreshBooks, Google Drive, Google Contacts etc…
• The ability to create list segments, which offer a way to split your list into smaller segments based on their previous purchase history, interests etc…
• The ability to A/B test your email campaigns.
• The ability to send the email campaign:
  • Immediately.
  • At a specific time.
  • At a optimal time determined by MailChimp.
  • Via Time Warp, which allows you to send out the email at a given time in each recipient’s timezone.
• Extensive analytics on both campaigns and lists.
• Functionality to allow subscribers to update their details at any time, or unsubscribe should they wish to do so.
• Etc…

As you can see, I’m a pretty big fan of MailChimp. How could you not be with such an awesome mascot, Freddie?

The API

Today we’ll be looking at how to use the MailChimp API to subscribe users to your MailChimp lists automatically using PHP. For example, you could use it to allow users to subscribe to your newsletter when registering to your website.

The first thing you’ll need to do is get an API key from MailChimp. You can do this by logging into MailChimp then clicking on Your username » Account Settings » Extras » API Keys. You then just have to click on Create A Key, and you will be provided with a API key.

Note – You should specify a label for your own reference, so you know which site each API key is for.

Next you’ll need to find out the list ID for the list you’re subscribing users to. In case you haven’t created a list yet, you can visit this page read the official support article by MailChimp.

Once you have a list set up, you can find the list ID by selecting Lists (in the sidebar) » The caret next to Stats » Settings. At the bottom of this page you’ll see the list ID, which is an alphanumeric value that’s 10 characters long.

Now that you’ve generated an API key and know what the list ID is, let’s go and download an API wrapper. An API wrapper is a collection of code that’s designed to simplify the whole process of interacting with an API.

If you go to the MailChimp API download page, you’ll see an extensive list of API wrappers for various languages/platforms; We’ll be using PHP and version v2.x of the MailChimp API. There’s quite a few wrappers to choose from, but as we’re literally just subscribing users to our list, we’ll be using mailchimp-api by Drew McLellan (requires PHP 5.3 or above). You can click here for the direct link to the download page.

To use the wrapper, we need to create the object:

[php]
include(‘MailChimp.php’);
$mc = new MailChimp(‘your-api-key-goes-here’);
[/php]

You’ll need to specify the API key you generated earlier when creating the object, i.e. replace the your-api-key-goes-here with your API key.

Now that we’ve created the object, we can go about subscribing a user to our list. You can do this using the call and lists/subscribe methods as shown below:

[php]
$result = $mc->call(‘lists/subscribe’, array(
‘id’ => ‘your-list-id-goes-here’,
’email’ => array(’email’=>’freddie@tastybananas.com’),
‘merge_vars’ => array(‘FNAME’=>’Freddie’, ‘LNAME’=>’Smith’),
‘double_optin’ => false,
‘update_existing’ => true,
‘send_welcome’ => false,
));
[/php]

Here’s a list of what each field above does:

• id (required) – This is the list ID of the list the user should be subscribed to.
• email (required) – This is the email address of the user you’re subscribing.
• merge_vars (optional) – You can use this to save additional information about the user, such as the first name and last name as shown above.
• double_optin (optional) – This defaults to true and dictates whether or not you want to use the double opt-in system. This means that they will receive an additional email asking them to confirm the subscription.
• update_existing (optional) – This defaults to false and specifies what happens when an existing email is being used to subscribe. If it’s false it will return an error message, whereas if it’s true it will update the information instead.
• send_welcome (optional) – If double_optin is set to false and this is set to true, it will send new subscribers a welcome email.

You can download a working version of the above code by clicking on the link below. Don’t forget to fill in your API key and list ID.

• Download

The object will return true along with MailChimp’s response JSON if the request was successful, or false if there was an error sending the request. You can use this to output an appropriate message to the user. Again, you can view the list/subscribe documentation to find out more.

Keeping an eye on your API

As with most things, it’s worth keeping an eye on your API calls just in case an issue arises. Luckily, MailChimp has a section on the API page that shows you details of the API calls made in the last 24 hours. Again, you can access the page by clicking Your username » Account Settings » Extras » API Keys.

And that’s about it! I hope you found this tutorial useful, and as always please don’t hesitate to leave a comment if you have any suggestions, questions or constructive criticisms!