Getting Started With the Mailchimp Marketing API

Mailchimp is one of the oldest, most reliable email marketing platforms out there. Even though there are newer, cheaper options for email marketing out there, Mailchimp still is the tool of choice for lots of online publishers and small businesses.

One of the reasons that Mailchimp stands out from the other email marketing options, is that they have a comprehensive API. This makes for endless customization and extension possibilities if you are comfortable with a little bit of coding.

If you are not as comfortable coding, there are plenty of no-code tools that are popping up to help you make use of the Mailchimp Marketing API. One of those tools is our own connector for Google Data Studio, which enables you to import your Mailchimp data in real-time to Data Studio, where you can then build custom reports and visualize your data with graphs and charts.

In this guide though, we will assume that you have some basic programming knowledge and are comfortable with APIs. This will be a very simple and practical demonstration of how to set up the Mailchimp API, how to get connected to it, and some basic examples of how you can pull down all of your Mailchimp lists using the Postman to access the API.

Before we dive into the details, let’s take a quick look at the tools we will be using.

Mailchimp Marketing API

This is the main API that Mailchimp offers where you can pull data about your Mailchimp lists, campaign performances, list growth and more. This is not to be confused with their transactional email API, which is different and is for sending one-off transactional emails.

Postman

For all of our examples, we will be using Postman. Postman is a simple, free tool that you can use for testing out API’s without having to write the rest of the code around it. This way, we can simply make sure that we understand how the Mailchimp API is working, before we look at writing a bunch of other code to do things with our Mailchimp data. If you are not familiar to Postman, you can get started here.

With that out of the way, let’s jump into it. We will be covering the following:

Creating your API Key
Finding your Mailchimp API Server Location
Using your Mailchimp API Key with Postman
Getting your Lists from the Mailchimp API

Creating Your Mailchimp API Key

In order to access the Mailchimp Marketing API, we need to create a Mailchimp API key. This can be done by logging into our Mailchimp account and going to the Account Profile.

From here, we will go to the dropdown Extras where we will see the option for API Keys:

If you do not yet have any API Keys listed, you will simply click on “Create a Key”. Then you will see it added to the list.

Note the key down since we will need it in our next step. And be very careful with is API key. Do not share it anywhere online, as anyone with this key will have full access to the Mailchimp API on your behalf.

This means someone could send lots of emails from your account or access all of your subscribers email addresses. In short, be careful! And if you do think that your API Key is compromised, you can simply delete it and create a new one.

Finding Your Mailchimp API Server Location

Next, we will need to find our Mailchimp server location. This is very simple as you just need to look up at the URL when you are logged into your Mailchimp account and see the first part of the URL.

For example, in this case, it would be “us13”. Ok, that was simple. Again, note that down, as we will need it to access the Mailchimp API.

Using Your Mailchimp API Key with Postman

Now we are ready to make our first API call to the Mailchimp Marketing API. To test this out without getting too complicated at first, we will just make a call to the easiest endpoint in the Mailchimp API: the Ping endpoint.

Essentially, this endpoint just let’s you know that you have successfully reached the API and received a response. Here’s how we access it.

The URL for the Ping endpoint is: https://[SERVER-LOCATION].api.mailchimp.com/3.0/ping

So if we follow our example from before where the server location was us13, the URL we would need to access to call the API would be: https://us13.api.mailchimp.com/3.0/ping

Great, so now that we know that, we can open up Postman and create a new GET request using this URL.

Now, if we press Send, we will see that we are halfway there - we have successfully received a message from the Mailchimp API, but it is telling us that we need to add our API key.

To do this, we will go to Headers and we will add the key “Authorization” with the value “apikey [OUR API KEY]”.

Once we’ve done this and clicked Send again, we will see a successful response from the Mailchimp Ping endpoint.

Getting Lists from the Mailchimp API

Now that we have successfully connected to the Mailchimp API using Postman, we just need to modify our request so that it does something a bit more useful. As a simple example, we will get all of our Mailchimp Lists from the Mailchimp API.

To do that, we will simply modify the URL in our Postman request, leaving the Authorization Headers as they are. First, let’s check the Mailchimp API Reference to see what the endpoint for fetching lists is.

Once we look it up, we will see it is: https://[SERVER-LOCATION].api.mailchimp.com/3.0/lists

So that means our URL will be https://us13.api.mailchimp.com/3.0/lists

Then if we enter that into Postman as we had done before:

We will see a response that looks like this:

{
  "lists": [
    {
      "id": "string",
      "web_id": 0,
      "name": "string",
      "contact": {
        "company": "string",
        "address1": "string",
        "address2": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string",
        "phone": "string"
      },
      "permission_reminder": "string",
      "use_archive_bar": false,
      "campaign_defaults": {
        "from_name": "string",
        "from_email": "string",
        "subject": "string",
        "language": "string"
      },
      "notify_on_subscribe": false,
      "notify_on_unsubscribe": false,
      "date_created": "2019-08-24T14:15:22Z",
      "list_rating": 0,
      "email_type_option": true,
      "subscribe_url_short": "string",
      "subscribe_url_long": "string",
      "beamer_address": "string",
      "visibility": "pub",
      "double_optin": false,
      "has_welcome": false,
      "marketing_permissions": false,
      "modules": [
        "string"
      ],
      "stats": {
        "member_count": 0,
        "total_contacts": 0,
        "unsubscribe_count": 0,
        "cleaned_count": 0,
        "member_count_since_send": 0,
        "unsubscribe_count_since_send": 0,
        "cleaned_count_since_send": 0,
        "campaign_count": 0,
        "campaign_last_sent": "2019-08-24T14:15:22Z",
        "merge_field_count": 0,
        "avg_sub_rate": 0,
        "avg_unsub_rate": 0,
        "target_sub_rate": 0,
        "open_rate": 0,
        "click_rate": 0,
        "last_sub_date": "2019-08-24T14:15:22Z",
        "last_unsub_date": "2019-08-24T14:15:22Z"
      }
    }
  ],
  "total_items": 0,
  "constraints": {
    "may_create": true,
    "max_instances": 0,
    "current_total_instances": 0
  }
}

As you can see, we’ve successfully pulled down data from each of our Mailchimp lists. If you want to get more details about what each of the fields means, you can refer back to the Mailchimp API reference.

Wrapping Up

With that, we have successfully connected to the Mailchimp Marketing API using our newly generated API key, and we have pulled down data for all of our Mailchimp Lists.

This just scrapes the surface of what can be done using the Mailchimp Marketing API and in future guides we will go into more detail on some of the more interesting uses.

And if you are interested in using your Mailchimp data to build custom reports and data visualizations, be sure to check out out our Mailchimp connector for Data Studio.