May 4, 2015 by Pete Holiday API

API v3.0 is Here

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

  • Bjoern Sjut

    05.04.2015 - reply

    Congratulations on the launch!

    Is there already an ETA for campaign creation via the API?

    • Pete Holiday

      05.05.2015 - reply

      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!

  • Léo

    05.05.2015 - reply

    Seems like a perfect timing to start with Mailchimp. Im developping a startup and I can’t wait to get started with chimp! =)

  • Scott Gatz

    05.05.2015 - reply

    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).

    • Pete Holiday

      05.05.2015 - reply

      Thanks, Scott! We’ll definitely be working quickly to beef up the documentation as well as the playground, API wrappers, and example code.

  • Bruner

    05.05.2015 - reply

    I did not think how to create a list in v3.

    • Pete Holiday

      05.05.2015 - reply

      Hi Bruner! List creation requires sending a POST request to the /lists/ endpoint with JSON describing a list. You can find the schema that describes a list here.

    • Pete Holiday

      05.05.2015 - reply

      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.

  • Khairul

    05.06.2015 - reply

    Hi Pete, when will you provide staging/sandbox environment? I didn’t find any mention in Mailchimp API documentation.

    • Pete Holiday

      05.06.2015 - reply

      Hi Khairul,
      We don’t have plans to provide a staging/sandbox environment at this time. We’ll add that to our feature request list for future consideration, though!

    • Pete Holiday

      05.08.2015 - reply

      Thanks for letting us know, Jose! We’ll get that taken care of!

  • Xiaobo

    05.08.2015 - reply

    Is there any plan to release a python wrapper for v3.0?

    • Pete Holiday

      05.08.2015 - reply

      Hi, Xiaobo! We do plan to release a wrapper for Python (and Ruby and PHP and Node.js) but we don’t have an ETA for that yet.

  • Bill Hyde

    05.08.2015 - reply

    The list and interests resources seem to only return the first 10 entries. How does one get the rest of them?

    • Pete Holiday

      05.12.2015 - reply

      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.

  • Pablo

    05.11.2015 - reply

    Is it possible to send an email campaign using v3.0? I can’t find the endpoint

    There used to be a campaigns/send method, but under /campaigns/{id} there are only /feedback resources.

    • Pete Holiday

      05.12.2015 - reply

      Hi Pablo,
      It’s not yet possible to create, edit, or send campaigns using API v3.0, we’re working on that functionality, though!

      • Ryan

        09.14.2015 -

        Think this is coming anytime soon?

      • Pete Holiday

        09.14.2015 -

        Hi Ryan,
        We can’t offer an ETA on that functionality right now. Because campaign creation is not well used it is behind some other features and enhancements.

  • Jonathan Blackburn

    05.12.2015 - reply

    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)

    Really encouraging API btw. Looking forward to the evolution in documentation, (php) wrappers and samples!

    • Pete Holiday

      05.12.2015 - reply

      Hi Jonathan,
      Retrieving a subscriber’s info happens just like you say, the only piece you’re missing is that, in v3.0, the subscriber ID is the MD5 Hash of their email address!

      • Jonathan Blackburn

        05.12.2015 -

        Oh duh! Thank you, Pete, and apologies for wasting your time!

        I am so smart… SMRT… etc…

  • Steve Cinquegrana

    05.13.2015 - reply

    Hi Pete,

    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.

    For example:

    https://us10.api.mailchimp.com/3.0/lists?apikey=181d353cc1ce044eccb1xxxxxxxxxxxx-us10

    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:

    1. Will there be a .Net wrapper (soon)?
    2. Thank god MailChimp is finally permitting List creation!!

    Cheers and thanks, Steve

    • Pete Holiday

      05.13.2015 - reply

      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

      06.15.2015 - reply

      Having the exact same issue, documentation regarding api key is extremely lacking,

      Hitting the link with a GET through the browser works fine, POSTing JSON like the docs say, no bueno, really could use better documentation guys.

      • Pete Holiday

        06.15.2015 -

        Hi Alex,
        We’re not seeing any issues with POST. The error message you’re getting back should tell you what’s wrong. If that doesn’t help, you should get in touch with apihelp at mailchimp dot com.

      • Steve Cinquegrana

        06.23.2015 -

        @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?

      • Pete Holiday

        06.24.2015 -

        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.

        Thanks for the feedback!

      • Steve Cinquegrana

        06.24.2015 -

        I rechecked this and PATCH calls require (eg for VB.NET/HttpClient): ‘Client.DefaultRequestHeaders.ExpectContinue = False’ as these headers are added automatically/transparently otherwise.

        This should go in the doco.

        PS Call made via Runscope endpoints work with the header left in.

  • Nacho

    06.18.2015 - reply

    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:

    curl -X GET -H “Authorization: apikey xxxxxxxxxxx-yyy” “https://us9.api.mailchimp.com/3.0/templates” -d ‘”type”: {“user”: true,”gallery”: false,”base”: false}’

    also:

    curl -X GET -H “Authorization: apikey xxxxxxxxxxx-yyy” “https://us9.api.mailchimp.com/3.0/templates?type=user”

    And even creating a {type:{“user”:true, “gallery”:…}} and setting it as a URL-encoded parameter with no luck.

    Could you possibly help me with this? Thanks a lot in advance.

    • Pete Holiday

      06.18.2015 - reply

      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.

      • Nacho

        06.18.2015 -

        Hi Pete,

        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).

        Best regards and keep up the great work!

      • Pete Holiday

        06.19.2015 -

        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:

        curl –user apikey:$MC_API_KEY “https://us9.api.mailchimp.com/3.0/templates”

        That’s a little bit more manageable and less custom. The way you mentioned earlier definitely works, we just want to make sure everyone knows that they can use HTTP Basic Auth!

  • Nacho

    06.19.2015 - reply

    Thank you Pete, actually, you were right (It’s been a long since last I used Basic HTTP Auth) thanks for your correction!

  • Lauri

    06.21.2015 - reply

    Is there any plan to add sorting feature to members resource?

    • Pete Holiday

      06.21.2015 - reply

      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.

  • Steve Cinquegrana

    06.23.2015 - reply

    Hi Peter,

    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?

  • Steve Cinquegrana

    06.24.2015 - reply

    Other issues I think are preventing adoption of v3.0 for production:

    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.

    • Pete Holiday

      06.24.2015 - reply

      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.

      Thanks!

      • Steve Cinquegrana

        06.24.2015 -

        Peter,

        All of this is already with apihelp.

        The Account schema is missing from Resources. It is available in the Playground.

        Cheers, Steve

  • Steve Cinquegrana

    06.29.2015 - reply

    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.

    Thanks.

    • Pete Holiday

      09.14.2015 - reply

      Hi Steve,
      We’re still evaluating the best options for a permanent changelog. For now, we will announce major functionality and bug fixes through twitter and our mailing list.

  • Israel

    06.30.2015 - reply

    Is there any ETA on when the new ecommerce features will be rolled out? Also with that being said can you point me in the right direction on the current API for ecommerce360

    • Pete Holiday

      09.14.2015 - reply

      Hi Israel,
      We can’t offer an ETA for addition of Ecommerce functionality to API v3.0 at this time. v2.0 is still functional, despite being deprecated, so I’d recommend using that for now.

  • Satish Bhadja

    07.05.2015 - reply

    hey we need to add member in subscriber list using an API v3.0.. but we are unable to do it as document is unclear.. can you help us on regarding that?

  • Jayesh

    07.08.2015 - reply

    How to use Mailchimp API in JavaScript without exposing the APIKey to enduser, if we use APIKey directly in JavaScript it can be easily hack. Please suggest me some solution.

    • Pete Holiday

      07.08.2015 - reply

      Hi Jayesh,
      We do not support client-side javascript API access. You’ll need to route your requests through a server you control.

  • Vladimir

    07.31.2015 - reply

    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.

    • Pete Holiday

      08.02.2015 - reply

      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.

  • Fabien

    08.05.2015 - reply

    Hi Pete!

    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?

    Thanks a lot!
    Fabien

    • Pete Holiday

      08.06.2015 - reply

      Hi Fabien,
      We can’t really do support via blog comment, but if you reach out to apihelp [at] mailchimp [dot] com they should be able to get it sorted out for you.

  • Damien

    08.18.2015 - reply

    I gave a test run to the new API, I find it much better than V2 overall, a lot simpler to use. Thanks and congrats !

    I was not able to filter though (e.g. on Lists) – is that implemented yet ? If not, do you have an ETA ? Without it, there’s just no way I can upgrade my existing code, I’ll have to keep using V2…

    • Pete Holiday

      08.18.2015 - reply

      Hi Damien,
      Filtering works fine on lists as far as I can tell. Can you get in touch with apihelp at mailchimp dot com to see if they can sort out the problem for you?

  • Max

    09.02.2015 - reply

    Is it possible to get all campaigns by subscriber email address using v3.0?

    • Pete Holiday

      09.14.2015 - reply

      Hi Max,
      This is not possible in API v3.0 right now, but may be added at some point in the future.

  • Todd Ingarfield

    09.03.2015 - reply

    Is it possible to bulk unsubscribe members from a list using the 3.0 API?

  • Lars Rathje

    09.06.2015 - reply

    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

    • Pete Holiday

      09.14.2015 - reply

      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.

    • Pete Holiday

      09.14.2015 - reply

      Hello, We still do not have an ETA for API wrappers. We recommend using a basic HTTP library or your own application-specific abstraction layer for now.

  • Yulu

    10.21.2015 - reply

    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?

    Thank you,
    Yulu

    • Pete Holiday

      10.21.2015 - reply

      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.

  • Dhwani Patel

    10.23.2015 - reply

    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.

    • Pete Holiday

      10.23.2015 - reply

      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!

      • Dhwani Patel

        10.23.2015 -

        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 ?

      • Pete Holiday

        10.23.2015 -

        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.

Comment