MailChimp is a great service that helps you manage your subscribers and send email campaigns. They offer easy to use signup forms that you can embed right on your site, but sometimes you might want a little more control over these forms. I recently had a project where the client wanted more customized success messages, and needed to be able to hook onto successful submissions with Google Tag Manager. This is where the MailChimp API comes in, so let’s take a look at a simple email subscription signup form that works with the API.
Generating your API Key
The first thing you’ll need in order to work with the MailChimp API is an API Key. Log into your MailChimp account and go to your account page. Under the “Extras” dropdown menu, click on “API Keys”. This page will show you a list of all your API keys, both active and deactivated. Click the “Create A Key” button to generate a new key. Be sure to edit the label to something like “Email Subscription” so you know what it will be used for. We’ll be including this in our PHP code later.
There are a few other variables you will need in order to create your subscription signup form: which datacenter your account uses and the ID of the list you want to subscribe new users to. The datacenter can be found either in the URL of MailChimp while you’re logged in, or at the end of your API Key, and should start with “us” followed by a number. The ID of your list can be found by navigating to your list in MailChimp and clicking on the “List name and campaign defaults” under the “Settings” dropdown. There should be a section called “List ID”. If you don’t see this here, you can also find your list ID in the MailChimp API playground.
The Markup
Because we’re not using MailChimp’s embedded form, we have a lot of customization on how we build the form. This means we can make our form more accessible, add custom classes or IDs, use different input types, and more. Here’s the markup for a simple form with options for first and last name and email, and an empty div to house our messaging:
The only field the MailChimp API actually requires is email, but you might want to include first and last name in your signup form as well. You could also add additional merge fields, such as a birthday or location, depending on your needs. Please note that only the email address will be validated, so you will need to setup your own validation for the other fields if you want them to be validated as well.
The JavaScript
On the JavaScript side, we’re going to trigger an AJAX call on submission of the form. It’s important to note that the MailChimp API only supports JSON, so we’ll be sending and receiving data in JSON format. Here’s an example of the AJAX submission:
As you can see, we have a couple of different messages based on what we receive back from the MailChimp API. In the first part of our .done() function, we check to see if the data includes an ID, since users who have successfully signed up will be assigned an ID. If the API wasn’t able to assign an ID to the user, we check to see if there is a title set to “Member Exists”. If this matches, that means the email address input by the user has already been used to sign up for the subscription previously. Finally, if neither of these matches or if the AJAX call fails, we return an error message. As you’re building out your form, you might want to return everything the MailChimp API is sending back to give you a better idea of all of the possible values.
The PHP
On to our processor, which we’ll be using PHP to handle. You’ll need to have your API key, datacenter, and list ID handy for this part. Here’s an example that uses cURL to submit our data to the MailChimp API and return the JSON we’re referring to in our AJAX call:
A couple of notes:
- The
$urlvariable is the endpoint for lists, and will need to know your datacenter and list ID to work. - The
$dataarray needs to be in a specific schema format to work with the MailChimp API.
Enhancements
While this is a very simple example, hopefully you can now see how easy it is to work with the MailChimp API. There are lots of additional enhancements you can make to further improve the functionality of the form, including better validation and accessibility. I went on to build this out as a WordPress widget, so that my client could easily add it to their sidebars and change the messaging as needed.