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.

What's different?

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.

What's new?

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.

What's left?

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!

Discussion

Thanks, Bjoern!
We can’t give you an ETA at this time. Our templates can, at times, be very complicated, and we’re currently trying to find the most simple and intuitive way to represent them. We decided to launch without that functionality because we weren’t yet happy with the design, but getting to feature parity with v2.0 is our top API priority, so I’m sure you’ll see that feature announcement on our mailing list soon!

Hey there, congrats. I know one of your goals was to improve documentation, but I’d love to see you focus more on that. It it completely unclear how to add a member to an email list, what fields are required? what’s the end point?

Also, a suggestion: add a link in each documentation endpoint to the correct part of the API playground (see facebook and foursquare’s documentation that do this well).

Hi Origami! In software parlance, “deprecated” typically means that the feature remains available but should be avoided as it may be removed in the future. By that definition, API v2.0 (and all versions prior) are already deprecated. As for when they’ll be retired and removed from service, we don’t know, but we’ll be sure to give plenty of notice both on Twitter (follow @MailChimp_API) and through our API Announcement mailing list, which you can sign up for here.

Hi Bill,
Pagination will be discussed in our documentation soon, but collections should recognize “offset” and “count” parameters. We limit the number of records you’re allowed to retrieve, but you can page through them with offset really easily.

It seems as though a request to GET the data on an individual subscriber hinges on sending “unique_email_id”… is there an API request that returns the same data by email address? Instead, is the expectation that unique_email_id is something stored on my end along with email in order to pass it through? Or is the idea instead that I upgrade to a paid account in order to do an embedded unsubscribe form? (totally fine btw, just a newbie here and getting the lay of the land)

Been looking at v3.0 today but am having some issues, quite a few of which could be solved with a bit better doco as a few people have mentioned, but also, I simply cannot get a JSON post to work apart directly in a browser.

works perfectly in Chrome and give me a list of my lists (well, one, as that’s all I have).

But if I use a modified version of the .NET wrapper, I get a 404 with “Your request did not include an API key”.

(I can emulate that error in Chrome by inserting a hyphen in “apikey” (“api-key”) and re-posting.)

I saw in your post above ”We removed the API Key from the body of requests and now support HTTP Basic Auth …”. But why is an API key still working in a browserand why is it required for the Playhouse? (It would be great if the Playhouse displayed the actual JSON post, btw.)

Anyway, this is getting a bit long but I have one last question and a comment:

Hi Steve,
Passing your API Key in the URL may still work in some circumstances, but it is not a supported authentication method. You’ll want to use HTTP Basic Auth (covered in our new Getting Started page in the docs) instead. The API Key is required for the API Playground because we’re making actual API Requests and the playground isn’t connected to your account in any way. All playground requests are fully visible — check the “Request” and “Response” tabs.

As for the .Net wrapper, we didn’t provide the .Net wrapper for previous versions and we don’t have any plans to do so for v3.0, mostly because we don’t have any developers in house with enough .Net experience to write a high-quality wrapper. I hope that the community will fill that gap as they have in the past, though.

If you have future problems getting your requests to work, please feel free to reach out to our API Support team at apihelp@mailchimp.com.

@Alex, FYI, PATCH calls don’t work. Well, they do via cURL and you can use POST tunnelling, but a standard PATCH call using any of the standard .NET libraries fails. This is confirmed by the API support guys.

I’ve put my integration release on hold pending availability of filtering (vital to limit data retrieval!), a working PATCH call and few other things that misbehaving and are currently with the developers.

@Peter, there doesn’t seem to have been any updates to doco in quite a few weeks (eg ALL Playground Request panes are still only showing an API Key, Account schemas are missing). Can you give us an idea when things will start moving again please so we can plan our work?

Hi Steve,
PATCH calls actually work just fine. The issue is with using the Expect: 100-Continue header and PATCH. This is an issue we’ve taken up with Akamai and hope to have resolved, but the better solution is to just not use that header. I understand that it’s useful in theory. Within our systems, however, we don’t process any requests until we’ve received the full body, so you’re not getting any benefits from using that header. Other API providers have run into issues with Expect: 100-Continue, as well, and some choose not to support it at all.

Things are definitely moving, but we cannot give timelines. Several integrations are already fully functional in v3.0, so it is definitely possible. The documentation is a larger effort, as we certainly didn’t do a very good job with that. It’s a very high priority but will take some time to do right. Sorting and filtering should be coming soon. In terms of other features, batch operations are also very high on our priority list. I’m not sure what account schema you mean, though. If you haven’t already, please reach out to apihelp about that one.

Hi. Congratulations on the new API. I hope you will add some more depth to the documentation, and some examples would be nice.

I’m having trouble because I find the documentation lacking in some areas. I.E. I’m trying to find out how to list just the user templates (not the base or gallery ones), but I’m clueless of how to do it. I have tried with:

Hi Nacho,
Sorry you’re having trouble! We don’t currently support any filtering on the templates end-point, you’ll just need to iterate over them for now. Once we add that filtering, you’ll be able to see it in the schema for the collection.

If you have other questions, you’ll want to get in touch with apihelp at mailchimp.com.

One other note: we recommend that people use HTTP Basic Authentication instead of just putting the API Key in the header the way you’re showing.

Thank you so very much for your prompt response. Sorry to hear about the lack of filtering support. Please let us know when it’s finally available!

I’m confused about your comment on the HTTP Basic authorization. Please correct me if I’m wrong, but according to wikipedia:

“When the user agent wants to send the server authentication credentials it may use the Authorization header. The Authorization header is constructed as follows: […]
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==”

So I’m using HTTP Basic authorization here, right? (The “apikey” was kind of a mistake on my quick writing, I’m currently using “Basic” for the requests).

Hey Nacho!
So in basic auth, the thing that comes after ‘Basic’ is not the API key, but the Base64 encoded string “username:password” or, in our case “anything:api_key”. The real benefit to HTTP Basic auth is that it is supported out of the box by virtually every HTTP library around. For example, in curl, you’d just do this:

Hi Lauri,
We do plan to add some sorting to Members, but we’ll be somewhat conservative in what fields we allow sorting on. Because some lists have a tremendous number of members on them, we have to make sure that all of the sorting options are performant.

Further to previous posts, although I’ve fed this back via apihelp, I figure there’ll be other developers looking here with questions and issues similar to my own. So …

Result retrieval is very, very convoluted at the moment with a need to pull three or four reports with seemingly disconnected and incomplete content. For example, one report is called “Email-Activity” in which you can get (only) ‘open’, ‘click’ and ‘bounce’ results (over time) for campaign recipients/subscribers/members (why three names for the one entity, btw?). There is no ‘forward’, ‘like’, ‘unsubscribe’, ’complaint’, etc info in this report. So you need to pull, say, the “Unsubscribed” report to get unsubscribes. Then there’s the “Sent-To” report which provides a static status field for (only) ‘sent’, ‘hard bounce’ and ‘soft bounce’ (but seemingly without a status date!). Bizarrely, the “Click-Details” report isn’t per-recipient but a Campaign summary! I’m yet to find a way to retrieve ‘facebook_likes’. None of these reports seems to have any way to filter on a ‘since_date’ so it’s entirely possible (though not obviously documented) that all results will need to retrieved every time rather than since last retrieval(!)

What’s needed here, I think, is either a complement of concise, consistent reports such as ‘Bounces”, “Opens”, “Unsubscribed”, “Likes/Shares”, “Complaints” – not forgetting “Unsent” for supressed addresses – or else a composite report wherein all of the various results can be retrieved per-Campaign, together or separately (via ‘fields’/’exclude-field’) and limited by date (eg since 7 days ago/June 1).

I’d be very happy to help draft these objects out, having design several API wrapper for various other providers. Just say the word.

PS The “Filters” buttons in the Playground is now often showing a new message: “We are still working on filter capabilities on the API Playground, but they work just fine on the actual API”. This is good, but where are the filter schemas for each object?

1. In the Unsubscribed report, the Reason field is empty for everything except ‘Other’ which returns the entered reason. ‘Normal’, ‘Inappropriate’, etc are not returned.
2. Quiet a serious issue with Bounces not being returned in the Email-Activity report. Opens and Clicks are ok.
3. ‘EmailType’ cannot be changed via the API; the change is ignored.
4. Using (hacked) PATCH calls often results in updated details not being return in the call. It seems to take either a re-PATCH or possibly just any subsequent call to get the correct/changed result.
5. There is no facility to set ‘Send A Final Welcome Email’ or ‘Send Unsubscribe Confirmations’ options in created lists via the API.
6. There is seemingly no way to get SocialStats, eg FaceBookLikes from API reports.
7. There is no way to get account User details via the API.

Hi Steve,
Thanks for all of this feedback! Blog post comments are definitely not the fastest or best way to get that feedback to the dev team, though. For bugs, apihelp is the best way to go, as they help the dev team isolate and reproduce the problem internally. For feature requests, apihelp will also work, or you can use the feedback form.

Sorry; I seem I’m polluting your blog, but I’d like to know if there is – or could be – a public API change log available to us. Eg, Playground is saying filters now work live, but we need some way of knowing when changed/fixes are released.

Hello. Congratulation for new version of API. I have several questions.
1) When are you planning to realize creating compaigns using API.
2) I can’t add members to a static segment. I use POST for /3.0/lists/{list_id}/segments/segment_id}/members but it gaves me an error: 404. Can you help me? Thanks.

Hi Vladimir, we can’t offer an ETA on campaign creation at this time. Because that is the least used feature of previous versions of the API, there are some other features (like batch operations) that will be worked on first. Because it is the most complicated endpoint to design, we will definitely take our time to try to get it right. We’re making steady progress, but can’t offer a timeline for you!

As for #2, your best bet will be to contact apihelp [at] mailchimp [dot] com.

Pretty awesome to use! It has been an easy journey so far thanks to your doc and examples, but now I am having some troubles while trying to PATCH a file via file-manager/files/{id}.
I am trying to change the name of the file and the content of the file, without any success (I could POST a new file via file-manager/files with success).
The request does not fail but the update just does not happen :/

I don’t have any crazy header such as Expect: Continue-100.
Is there anything I can be missing?

Great API and good documentation.
But I really miss some filtering on member lists. Or if too heavy for your request, why not a segmented list of members. That would be a starting point, so we can use the filtering from segments to avoid loading all members through the API just to check for a few that need a certain action.
Is this scheduled? Right now you can only get number of members on a segment.
Best regards
Lars

Hi Lars,
We don’t plan to support much in the way of advanced filtering of the members endpoint — segmentation is the right way to handle that. Accessing a segments members is something we hope to add once in a future update.

Can 3.0 create/update a particular template?
I tried get a template by id and returned back a json file of its information but not including the body of the template. Am I looking at the wrong document or is Api currently does not support them? Is there any possibility that the api will support them in the future?

Hi Yulu,
We do not currently have a timeline for template creation in API v3.0. That’s a very seldom used endpoint in API v2.0, so there are other features (like campaign creation and ecommerce) that are higher priorities right now.

I am trying to do http GET / Post requests using apikey and userid. It works fine with curl but when I do ajax call it gives me “Access-Control-Allow-Origin” error.

$.ajax({
url: ‘https://XXXX.api.mailchimp.com/3.0/lists/XXXX/members?user=XXXX&apikey=XXXXXXX-XXXX’,
type : ‘POST’,
contentType : “application/json”,
data : {
“email_address” : “abc@email.com”,
“merge_fields” : {
“FNAME” : “firstname”,
“LNAME” : “email”
}
},
error: function(data) {
console.log(‘error’);
},
success: function (data) {
console.log(data);
}
});
What is the best way to handle this? I tried to use Jsonp to avoid the error it works to get the data but still response is not fully jsonp so it does not look like you have jsonp response set up.

Hello Dhwani,
We do not support accessing the API via client-side Javascript to avoid the security issue of passing your API Key along to your users. If you have further questions, apihelp at mailchimp dot com can assist!

Okay… that makes sense and I started with playing Java wrapper And it gives me invalid authentication key. I understand it was as is from v1.2 — do you have any new updates to support as for java wrapper ?

We plan to offer some wrappers in the future, but we do not have an ETA or a complete list of languages that we plan to support. For now, your best bet may be to make plain HTTP calls to the API instead of relying on a wrapper.