May 5, 2015

Announcing MailChimp API v3.0

MailChimp’s API has come a long way since its 2007 debut. Two years in, it had nearly 20,000 users. After four years, we were processing 10 million requests per day. Now we handle more than 80 million requests every day from a quarter of a million users. These users are employing the API to subscribe people to their lists, sync their accounts with other web services, use our mobile apps, and send campaigns.

Today, we’re excited to announce the official release of MailChimp API v3.0. The new version is more organized and less confusing, with all the flexibility and power of previous versions. It has a few new features, with more on the way. For a detailed look at the changes, visit our developers blog. Here, we’ll walk you through the process that got us to v3.0, and give you a peek at what’s in it.

Last year, we surveyed some API users. The results were mostly encouraging, and more than 80% of the responses cited the API as a very important factor in choosing MailChimp. But not all of the reviews were positive, and we were left with the lingering question of why so few users transitioned from v1.3 to v2.0 back in 2013. When we looked into that, we learned that some developers found the API not-so-easy to use. For some of them, it was too complex—v2.0 of the API has more than 120 distinct endpoints (for comparison, there were 32 endpoints in v1.0). Others noted that the documentation was inaccurate in some places and vague in others. Most discouraging of all, we heard complaints about some bugs in the API behavior that were making it hard for people to get their work done.

At MailChimp, we’re committed to innovation and addicted to improving things for our users. So even though v2.0 was barely a year old, we realized it wasn’t as great as it could be, and we got started on a new version.

Experimenting with complexity

We knew the next version of the API had to be every bit as flexible and powerful as previous versions, because those characteristics are the foundation upon which so many great integrations are built. With that in mind, our first experiments were just small tweaks to v2.0’s structure. We tried to organize and simplify the different API calls, and we explored what it would take to guarantee that the documentation would always remain true to the API’s actual behavior. We hoped we would find a fast and easy miracle cure. Ultimately, those experiments failed. The API’s complexity was inherent in its design, and that complexity was the root of almost all of its problems.

The API needed major work. So we started reading—books, blogs, and Ph.D. theses were all on the docket, as was the documentation of other APIs. The finish line was still a long way off, but thanks to our extensive research, we came up with a plan that would let us build a more intuitive API from scratch. And we wanted to make sure we didn’t finish this project and find ourselves looking at another major rewrite 12 months later. We wanted to do it right.

Our new and improved API

Version 3.0 of the API has been through months of development and internal testing. We’ve had it in public beta for 2 months. With this launch, the API is stable enough that applications and integrations can start offering v3.0 functionality to their users. There are some major new features, too:

  • List creation
  • Adding people to your list in an ‘unsubscribed’ state (this is excellent if you’re joining us from another email service provider)
  • API-triggered automation emails
  • Ability to upload images to the file manager through the API

E-commerce and campaign editing tools are coming soon, and we’re always keeping an eye out for opportunities to add even more power to your MailChimp integrations.

If you want to take a deeper dive on the new features and the changes from v2.0, we’ve got you covered. For starters, our engineering blog gets into more of the technical details. And you can keep tabs on future API updates by following @MailChimp_API on Twitter or subscribing to our API Announcements mailing list.