Today we're releasing API v3.0 to the world. The public beta went well, and we've squashed a ton of bugs and gotten good feedback on areas that were still too confusing. It's now available for everyone to use in their MailChimp integrations. Let's get into the details.
The short answer is: almost everything. V2.0 of the API was a weird hybrid of RESTful and RPC practices, which required everyone to learn our own special style of API design. With a few minor exceptions, API v3.0 is fully RESTful. This allows us to express in a couple dozen resources what it took the last version 120 distinct endpoints to accomplish.
Converting to a RESTful API has many benefits. We now support GET, POST, PATCH, and DELETE, operations that do exactly what you'd expect them to. We revamped our error serving process to ensure that you'll get useful data when your calls fail, and we're using more appropriate 4xx and 5xx error codes. We also now return HATEOAS links with all responses, allowing you to navigate and discover the API without constantly referencing the API docs.
We removed the API Key from the body of requests and now support HTTP Basic Auth in addition to OAuth2. Basic auth is by far the easiest way to get started using an API. It's understood by virtually every HTTP library and can be done easily on the command line or in the browser.
We're phasing out all the older, different ways of referring to a list subscriber and focusing on a new and improved one: A subscriber's ID will now be the MD5 hash of their email address. This will allow your code to sync subscriber data without needing to keep track of MailChimp internal IDs.
In addition to all that, we've made tweaks to language throughout the API to make it more intuitive. This means, for instance, that you'll never have to try to remember the difference between an Interest Grouping and an Interest Group ever again. Phew.
All API responses now return a header link to a JSON Schema document describing their contents. This, along with the new HATEOAS links mentioned above, means you can build a fully-functioning API integration without ever setting foot inside the API documentation.
For the visual learners out there, we've also developed an API playground where you can navigate through the API over the web and see exactly what data is required to make a request and what gets returned. You can even look at the related schema documents.
On top of those structural changes, we have some new features as well. List creation is now available in the public API, which can reduce the number of steps a new MailChimp user might need to take to set up an integration manually. We're finally offering programmatic access to automation workflows, and there's even a special workflow that lets you trigger emails with an API Request. Oh, and we've exposed the File Manager API, including the ability to upload images.
Our brand new API documentation has been reviewed and reorganized to make it easier to find your way around, and our API responses and schemas will point you to the most relevant page in the API docs. Boom.
Nearly 90% of our API traffic makes use of either the list management or reporting endpoints. Because those calls are ready to go, we want to get them out into the wild—but there's still some functionality from v2.0 that isn't yet reproduced in v3.0. Most notably, keeping the creation and editing of campaigns simple has proven to be a tough design challenge, so we're still iterating there. The e-commerce API is being re-imagined to be more flexible and useful for retail integrations. Those resources, along with a couple of other roads less traveled, will be added in a future release.
Other future development plans, including introduction of batch operations and better API wrappers, can be found on our API Road Map. For now, we look forward to hearing your feedback as you dig into MailChimp API v3.0. Happy integrating!