Mar 4, 2015 by Pete Holiday API

API v3.0 Enters Open Beta

A few weeks ago, I wrote about some of the issues we discovered when we took a hard look at our API v2.0. Today, I'll show you how we're fixing them.

Many of the problems people encountered with older versions of the API were systemic or architectural. But since we can't make backwards-incompatible changes, the only way to make things better is to release a new version. So that's what we did. MailChimp API v3.0 is now in public beta, and I'm here to tell you all about the improvements it'll bring.


The most frustrating thing about v2.0 was its inconsistency. That was never more obvious than when the documentation described one thing, but the API did something else entirely. Oof. While the existing documentation inconsistencies could have been fixed without creating a new version of the API, we saw the errors as a symptom of a larger problem. It was too easy to modify an end-point without updating the documentation, and too easy to create a new end-point that was inconsistent with other end-points within the API. The architecture of v2.0 and its predecessors was too flexible and open-ended. It didn't lead developers down the right path. And when your system makes it easy to go down the wrong path, you shouldn't be surprised when that's where your developers end up.

We fixed that in v3.0 by baking in the consistency. We used JSON Schema to describe the input and output of every endpoint. More importantly, the API itself now makes use of those schema files to validate user input and generate the responses, making it very difficult to produce inconsistent output. Those schema files are also a key piece of both our documentation and our new libraries.

All of those problems could have been solved behind the scenes, at least in theory. In practice, it would have been incredibly difficult to maintain perfect backwards compatibility (including replicating our long-standing bugs) while also changing the core architecture. That's especially true because we didn't have a source that we trusted to describe the API perfectly.


Fixing v2.0's architecture issues in-place wouldn't have allowed us to address the other major issue: its complexity. API v2.0 had more than 100 different methods, all of which took their own inputs and produced their own outputs. Those end-points weren't particularly intuitive. It was nearly impossible to develop for the MailChimp API without constantly referring back to its documentation, even if you were using one of our official libraries. There was no good way to hide that complexity.

But our switch to a RESTful API helps tame that complexity. API v2.0 consisted of an eclectic mixture of nouns and verbs. In v3.0, we've replaced them with resources (nouns), and you indicate what you want to do to them with standard HTTP methods (GET, POST, PATCH, and DELETE). Once you learn what resources are available, it's easy to predict what calls you'll need without having to page through the documentation. Simpler, and less time-consuming.


The new version also enables a more robust feature set. By launch, you'll be able to work with automation, create lists, upload files to the file manager, and work with drag and drop campaigns and templates. And that's just the tip of the APIceberg. We have a number of exciting new features we're not quite ready to share with the world yet, but stay tuned.

Getting started with v3.0

In the meantime, we'd love for you to dig in. While we put the finishing touches on our official documentation, we have some temporary resources to help you find your way around in our examples repository. The only thing we ask is that you hold off on pushing your new code to production, because we can't guarantee that any of the end-points will remain in their current state between now and our official launch. But that also means that we're eager to hear your feedback. Email with your questions or comments. We can't wait to see what you build!


  • jeremy French

    03.05.2015 - reply

    Just finishing a big project based in the v2 api. Yes I did have to refer to the docs often.

    But did I just read that you will be able to create lists with the v3 api? That was the only manual part of the process so it would be great to be rid of it.

    • Pete Holiday

      03.05.2015 - reply

      Hi, Jeremy! That’s correct — you’ll be able to create lists with v3.0 of the API. That functionality is already available in the beta version of the API, if you want to try it out!

  • The Digital Orchard

    03.15.2015 - reply

    You are asking not to use v3.0 in production yet, but I’d hope to avoid making a big jump from v2 to v3 sometime in the future. My development time for v1/v2 has already been far in excess of any other API that I’ve implemented due to the sheer complexity. If I can jump straight to v3 knowing that you are still finalizing some of the details, would you have any objection? I have a very small clientele and don’t make my software publicly available, so I would not be distributing an application that may end up broken. Instead, if you do make some drastic changes to the v3 API, I’d be able to update my code and installations fairly quickly. Thoughts?

    • Pete Holiday

      03.15.2015 - reply

      The rationale for asking that v3.0 not be put into production yet is primarily to keep folks from deploying code that we could break at any moment. As long as you’re okay with that risk, we’re not going to stop you from pushing your code live.

      One suggestion for anyone planning to do this: be sure to catch any errors that might come back from the API and make sure the logs of those errors are highly visible to your dev team! This is good advice even if the API is not in beta, but it’s critically important if the API is in a state of flux.

  • Anthony Moore

    05.05.2015 - reply

    Hello, just wondering when you can expect us to use 3.0 in production. I have a case where I can not use version 2.0 because it uses cURL.

    Also, do you happen to have docs on subscribing and un-subscribing users with v3.0?

    • Pete Holiday

      05.05.2015 - reply

      Hi Anthony!
      Your timing is excellent. API v3.0 was released today! Just so you know, we don’t require cURL for any version of our API. To subscribe a user in v3.0, you’ll just need to send a POST request with the subscriber’s info to the appropriate list’s members endpoint. It’d look something like /lists//members. You can read more about the available resources on our docs.

      • Mitch Berkson

        05.13.2015 -

        Could you give an example of exactly what the endpoint would look like to subscribe someone? How would associated information (first name, last name, etc.) be written?

      • Pete Holiday

        05.28.2015 -

        Hi Mitch,
        In general, the easiest way to figure out how to create the request JSON is to copy the format that we send you when you request that same type of resource. You can also make use of the JSON Schema for that resource, which you can find on the API Playground. For more details on subscribing users, please check out this knowledge base article:

  • Paul Vaswani

    05.28.2015 - reply


    We have been working on an integration using API 2 but are now considering whether we should switch to API 3 before release. I prefer API 3 in every way but it would be really helpful to have some rough idea of your timescales for completion. Can you give me even a ballpark idea of when you anticipate having the insert and edit functionality available across at least the most commonly used endpoints?

    Many thanks,

    • Pete Holiday

      05.28.2015 - reply

      Hi Paul,
      We can’t offer an ETA, but we have completed the API across the most commonly-used end-points already. Around 80% of our our API traffic is list management, around 10% is reporting and statistics, those are functional already. The most obvious missing piece is campaign creation, but that accounts for a very, very small percentage of our API traffic. I hope that helps!

      • Paul Vaswani

        06.03.2015 -

        It’s definitely list management that we are interested in but for us most of that revolves around creating, maintaining and updating interest lists. From my experiments in the API playground those create and update facilities don’t seem to be live yet.

      • Pete Holiday

        06.03.2015 -

        Hi Paul!
        Creating, maintaining, and updating interest lists is definitely live and working. The playground does not offer create or update for any resources at this time, but the API does support it.

      • Paul Vaswani

        06.04.2015 -

        Hi Pete

        How did I miss that!? Just assumed that the playground offered the full API… Many thanks for the clarification.

      • Jesse

        06.10.2015 -

        Pete, you say creating a list is live and working in v3… how do we do it?

  • Andrew Newby

    10.07.2015 - reply


    The new API looks great, but I can’t seem to get it to work :/

    As per the example here: … I’m doing:

    curl –user apikey:xxxx-us6 –request PATCH “” -d ‘{“email_address”: “”, “status”: “pending”, “merge_fields”: { “FNAME”: “Test”, “LNAME”: “Bar”}}’

    While I get a result… all it seems to be is a list of current subscribers (not including my new one) … and I also don’t get an email asking me to confirm :/

    Any ideas?