MailChimp’s API, V2

New MailChimp—AKA: Chinchilla—is here. (OK, so maybe only one other person calls it chinchilla.) Coincidentally (a coincidence since this has nothing to do with that), we’ve also released a totally re-architected version 2 of our API. The version 1.x series has proven plenty useful for years, but it’s old and was built before most modern principles of API design really caught on. Our major goals while revamping the API were:

The first thing to keep in mind while reading this is that, as you continually say to yourself, "Duh, why didn’t you do that before?" remember that API functionality typically needs to be backwards compatible, and stay stable across major versions. In other words, consider the effect some of these changes would have on existing code if we just changed stuff. Which is to say: none of this applies to v1 of the API! All right. Onward!

More RESTful

We’re by no means REST purists, so we’ve implemented the principles that we like the most and eschewed the ones we kind of hate (like "proper" verbs). First and foremost, proper HTTP response codes. In the version 1.x series, any call to a valid API endpoint/method would return a 200/OK (unless we really had broken something good [thankfully that rarely has ever happened]), even if an error actually occurred. Now, any time we’re returning an error, you’re going to get a 500 response code and the response body will contain the details of the error. Many folks will recognize this makes error handling even easier since you don’t have to parse a response body to figure out what happened even though you’ll probably eventually want to. For anyone who had noticed/relied on our X-MailChimp-API-Error-Code (that contains the error code that’s in the response body), fret not—it’s still there, too. One exception to this rule is that the various batch methods will always be returning a 200 with error codes inside them—not really anything we could do there. Anywho, then, as you’d expect, calls that work without error will return you a nice 200 response and you can deal with whatever they send back.

Next up, the URL structures are vastly different. Version 1 documentation always split methods up into various categories (List Related, Campaign Related, etc.) and used funky camelCasedMethodNames (that weren’t always even consistent—yes, we’re looking at you, xxxAIM methods [more on those later, too!]) and generally required you to always pass said method name via the "method" GET parameter (please don’t use XML-RPC). So silly. Things have been moved around, renamed, namespaced, and generally made to make more sense. GET parameters are no more (we’re begrudgingly going to support them because POSTing is "hard"), but would generally rather they not be used. Because POSTing really isn’t hard. The URLs also match some of the app’s URL schemes a bit more closely, which we hope proves a tad helpful. Some examples, you say? Sure:

If you’ve worked with the Mandrill API, that should seem eerily familiar. Good! Lastly, and this really has nothing to do with REST, but API v2 is HTTPS-only.

Standardization and extensibility

I like big words. That really just means be less dumb and give ourselves room to expand so that less dumb has to be done in the future. Version 1 of the API has (jankily) supported POSTing JSON objects in lieu of using serialized HTTP parameters for quite a while. Why jankily? Because you had to urlencode them (don’t ask). That was unnecessary, and version 2 removes that. JSON objects, of course, must still be POSTed (but you’re POSTing any way, right? RIGHT?). Serialized HTTP parameters are certainly still supported as input parameters as well (and you should POST them!). JSON as an output format was even more janky because we weren’t paying attention when it was implemented. How so? The JSON standard—and thus, most libraries that implement it—does not like scalar values (makes sense, they aren’t objects or collections), such as the tons of places v1 would just return a boolean or string value. Of course, PHP on the other hand, turns out to be totally cool with encoding/decoding a pure scalar value (it doesn’t, it just passes them around), and that’s what we failed to pay attention to. Whoops. That’s fixed—every return value is either a struct or an array.

Which segues nicely into this: A longtime pain point has been that languages of the programming variety don’t call the same/similar data structures the same things. We often tended to just go with calling everything arrays the way PHP does. It might be an array or it might be an associative array (hashmap, struct, dictionary, tuple, and on and on and on), and that confused/frustrated folks, especially when they didn’t look at raw data being returned (no one does that). There’s only so much that can be done about that, but we’re trying really hard in the documentation to consistently call things in these manners when describing input/output values:

Arrays will be pure arrays that just contain a bunch of items (no keys!).

And, of course, arrays may contain structs and structs may contain arrays.

Next up, we’ve moved to using more nested input parameters where possible. For one example, where "start," "limit," "sort_field," and "sort_dir" previously had been listed as separate parameters, we’ve often collapsed them into an "opts" struct. The point there is to make huge method signatures a bit smaller (which really just matters in API wrapper-land) and make it significantly easier to drop new options in without affecting signatures and the such. In other words: we’re lazy.

Finally, we started working on getting you more data in a more standard fashion (more on this in a minute). What that means is where we may have just returned a single email address alongside report data, we’re now going to dump out a full member profile record (this is basically what you get from the v1.3 listMemberInfo() call). Ditto for campaigns and places that may have just returned a campaign ID instead of a full set of campaign data (for example, searchCampaigns()).

Clean up time!

This is partly just an extension of everything already said. However! As mentioned above, HTTPS will be required—no more HTTP-only support. The ridiculous API Key "security related" methods that never should have been added in the first place will not be making an appearance. If you ever wanted to get, say, the members who opened a campaign, you would have found yourself using the oddly name campaignOpenedAIM() method. Wait. AIM? What in the world is that? Well, that is the very definition of old, old, old cruft. Many moons ago, A.I.M. stood for "Actionable Intelligence and Metrics," and was actually a paid add-on. Then weandourservers grew up some, renamed that to the more sensible, less-obtuse "Subscriber Activity," and made the data free. As it should be. Because it is yours. That’s my long-winded way of saying that, in v2, you’ll now be calling the more reasonably named /2.0/reports/opened method. This is pretty minor, but if you’ve ever left off basic required parameters you’d be presented with a -99/XML_RPC2_Exception error code. That’s now going to be a more logical ValidationError/-100. The actual error message text being returned will still generally be the same and explain issues in detail as would be expected.

Match the app + improvements

One of the most amusing things is the number of times people believe that the API is some magical thing that lets you do all sorts of crazy stuff that our service doesn’t support or can end-runhow things work. Ha. Nope. Our API—just like most any you’d run into—is generally meant for automating what you can do inside the app. But you knew that. V1 mostly does match what you can do in the app, but over the years things change and can fall out of line a bit. It’s also infinitely easier to drop a UI change on folks since there’s little-to-no need for considering backwards compatibility—and that happens.

Not so much with the API. But with a sparkly new one, we can kind of do whatever we want. So, first up was to match the various "data tables" folks are used to seeing in the app. Using our new /reports/opened call as an example, where it used to simply return an email address and the number of opens, it’s been expanded to return the number of opens and that entire member profile data structure previously mentioned as well as allowing the same sorting as the app. Ditto for the other "subscriber activity" report data plus the lists/members call (that’s been a pain point for a while). However, due to returning WAY more data along with increased load from the potential heavy lifting of sorting, those methods are also now going to be limited to a max of 100 records (where they previously were at 15,000). Part of the hope with that, as well, is that people will stop trying to use them for doing huge syncs since we have our lovely Export API for that.

Next, you may remember that we launched ACL/multi-user accounts/permissions/whatever support back in v8. Since then, however, only logins with the admin/owner permissions actually had API access. Version 2 changes that in a number of ways. First, where our OAuth2 implementation would not allow logins with viewer/editor/manager roles to "log in," that restriction is being removed. API Keys/tokens issued will now be tied to those logins (so we know what permission level they have), and API methods have been limited to appropriate roles based on how they work in the app. Which is to say: a viewer has access to reports/opened , but most certainly not to lists/members or campaigns/create. Second, there are a number of new users/* methods that will allow admins and owners to manage the logins with access to an account via the API should someone want to do that. So, whee.

Another pain point that required some significant changes was how our "unique" IDs worked for accessing/changing/etc. list member data. Basically, it’s always been unique to an email address, not to your list member, so they were useless for scenarios where you wanted something truly unique to a member that wouldn’t change (like when changing email addresses). We’ve always had something that would work for that, but it’s now clearly exposed, and the majority of places an email address or unique ID would previously have passed will now accept that. You’ll also find we’ve explicitly defined a standard struct for passing that data. The last big win here was redoing how merge_vars are passed in lists/batch-subscribe and lists/subscribe. Essentially what you’ll find is that lists/batch-subscribe takes an incredibly more sane data structure for defining those things and that it, list/subscribe, and list/update-member get these nifty modifications:

GROUPINGS will now be passed in a pretty array/struct setup—no more crazy, potentially escaped comma delimited strings. That’s a general change we’re aiming for across the API.

MC_NOTES will now allow passing multiple notes to add/change/delete/etc. rather than a single one. Previously multiples could be done in one call via listBatchSubscribe, but this makes that slightly easier.

There you have it: a pretty comprehensive overview of how and why we’ve re-architected the API and what to expect. API v2 is now fully available, and we’ll start posting detailed change logs for methods and such soon. As with any code changes this massive and completely new, we’ve slapped a nice little beta type tag on it and will not immediately commit to anything changing for a few weeks as people poke and prod it and yell at us about things we missed or screwed up. That said, it’s certainly been going through tons of internal testing, so we’re not anticipating too much of that, though we’d asinine to believe it won’t happen. If you’d like to follow along, subscribe to the API Announcement Group, the API Support Group, or keep an eye on our @MailChimp_API twitter account for updates and announcements about v2.

Hi Fawn, You can find My Templates by clicking on “Campaigns” and then looking in the upper right corner next to the Create Campaign button. You can click the link for a screenshot of what you’re looking for.

I just sent some feedback, to be perfectly honest I find the new Mailchimp outright awful. Now while some of that intiial sentiment may be going away after using it for a bit, there are a couple of key features simply gone (or hidden).
-I can’t sort the ‘opened’ list by user activity (‘opens’) anymore in the report.

-the GIANT search field makes me feel like a sighting impaired 3 year old and is an absolute outrage in terms of privacy (EVERYBODY can see for what / whom I search from 3 miles away)

-general navigation: why did you change it, it was neat, simple & clear before. It’s confusing and less user friendly in my HO now. Took me ages to find to the ‘service’ and ‘billing’ and ‘support’ bit.

Lastly, agree with Don, I don’t need to see somebodys whole entry bit so interesting suggestion…

In general, I’d prefer much more economy of use of space use on the whole site and much less of a ‘mobile’ reduced / constrained feel. Sorry for not bearing a more positive comment.

Hi Alison, If I’m reading that correctly, I believe you’re referring to the location data under the subscriber profile. Sorry about that, it’s a definite whoops on our part and it looks like we left that out of the new version. That being said, I believe it’ll be returning soon.

Can you tell us more about where in the Reports section you’re having trouble sorting by opens? If you’re in a Report > Subscriber Activity > Opened, clicking on the “Opens” column will sort your data for you. Maybe you’re talking about another area?

Our goal with the search feature was to make it quickly available, big and dead simple. We know people have a lot of data and want to access it quickly. I don’t follow on the privacy issue. Your data is only searchable by you, no one else has access to it.

We changed the navigation to make better use of the space in our app, and standardized things so when you learn where things are one time, you can find what you need in other sections. There will certainly be a little learning curve as folks get their bearings with the new look, but we think it’ll be temporary and will ultimately result in faster workflows.

Hi Chimps,
First, it is hard to find a place to make suggestions on the new design. So, I hope I’m in the right place.
Second, it was hard to find Campaigns, now I know that it is found by clicking the icon on the left that says Design and Send Emails–not obvious, it is hidden from a new user, counter-intuitive.
Third, the Campaigns page is what I use the most and it is now worse than before. I don’t mean worse as a visual design but as a usable design, the colors are okay but the campaigns are not sorted in a descending date order, at least on the old design I could click the top bar and sort this info. Also, there is not a clear visual separation between each campaign. On the old design the row that I placed the mouse was highlighted, this was useful.
Fourth, on the Campaigns page at the right bottom there are buttons to browse the next campaigns on the list. These buttons are not as helpful as they should be. a) these buttons do not say Newer and Older, instead these say Previous and Next, which is confusing as this nomenclature does not indicate a clear direction. b) Also, these buttons are missing at the top of the list. It is necessary to go to the bottom of the page to click Previous or Next every time one wants to see the top of the next page–lots of extra wasted time. Check how this is done in gmail. BTW, I’m not fond of gmail but they got this point covered.
That’s my rant. I hope these points get fixed for a more friendly, usable experience.
Thank you,
Oscar

Hi Oscar, Thanks for the feedback and this place is just fine, but you’re also always welcome to use our Feedback Form as well. That being said, I’ve made sure your thoughts have been passed along to our UX team.

Hi Shay, Hrmmm, that sounds like something that might be resolved by clearing your cache and cookies or potentially even trying another browser. If you’re still having some trouble, would you mind reaching out to our support chimps at: http://mailchimp.com/chat so they can help get you back on track?

Hmm. Just wondering: could you let you customers decide if they actually would like to use the new design or if they prefer to stick with the old one (you know, like Google does when they phase in new services)…When I posted my ‘rant’ earlier, I wasn’t really sure if it’s just me but reading just a few more comments (Holly, Shay, Oscar etc) I’ve got a feeling that I’m not entirely alone with my slight disgrunt.
And I really thought the old chimp was pretty matured, so I really didn’t need to learn yet another interface UIX etc…it was just good’n’ solid as was. And I’m normally not a traditionalist. At all. Anyway…just a thought.

Hi Jenny, Sorry about that. It looks like one of the newest versions of FireFox is causing some intermittent issues similar to what you’re describing. I know our devs are looking into it, but in the meantime, you could try shutting down your browser (assuming you’re using FireFox) and restarting it which seems to help sometimes, or temporarily switching to another browser like Chrome or Internet Explorer v8 or newer. Additionally, if you have other questions or feedback, please don’t hesitate to reach out to our support team at: http://mailchimp.com/chat

I know I’ve not been too polite in my previous post but would have hoped that the constructive criticism would solicit some kind of response; after all you should value the fact that I’m taking my time to give you feedback (even if you don’t like it). I’m a paying customer and your changes (if they remain) make me consider the option of leaving. I still can’t sort the ‘opened’ column, the search box is still not substantiated from a methodical or functional or aesthetic perspective and most answers that you give to comments are on a technical level. That makes me think that you’re viewing your product pretty much purely from a tech perspective (I don’t understand any of the chat preceding these comments about tech stuff).
You should acknowledge that some of your clients chose you above others because you had something that just worked. In terms of user interaction. Now it doesn’t anymore. Pls respond.

PS the mobile screen from which I’m writing this from doesn’t work well either (iPhone). Which is surprising since the whole interface feels like it’s geared towards an app feel.

Hello Aarron
thanks for getting back. So the ‘open’ sorting works now (it was unresponsive in two browsers (chrome & safari) at the time i submitted my previous comment), which is good news.

In regards to the HUGE search box: of course I assume that privacy is given from a technical perspective, but what I was referring to is that anybody can simply read whatever it is that I’m typing into that ridiculously HUGE search box from literally miles away. It practically fills up the whole screen! I simply consider it counter-intuitive if a search field makes me feel like a 3 year old playing with Duplo…

Re the general UIX, everybody in our organisation who’s got to work with it is not fond at all of the changes I’m afraid to say. It really does feel like an app-gone-wrong. We’ll test it for a bit, maybe we get used to it. All best

Sure thing Peter. If you’ve created a custom template, just go to “Campaigns” and then in the upper right hand side, click “My Templates.” At that point you’ll see any templates you’ve created and the “Edit” button right beneath each one followed by a small downward facing arrow. Just click the Arrow beneath the template you’re wanting to export and a dropdown will include an option to export.

Hi Pernille, Thanks for being a MailChimp customer and taking the time to share your feedback. With a change this large, there’s always a time of refinement and having this kind of feedback helps that process. I’ve noted your above thoughts and passed along to the UX team, but I am still a little unclear as to what you mean by “Everything flows together.” Could you give me a few more details or even send a screenshot to blog at mailchimp dot com so I can take a closer look? Thanks.

Sorry to say that I really don’t like the new version. I find it difficult to use and I cannot get the Search feature to work at all. If I want to search for a list subscriber (which I often do) I can’t. When I click the search button it just takes me to tips.
Can we get the old version back???

Hi Nancy, While tips do show up just beneath the search area, you should be able to click right next to the magnifying glass and start typing your name, email, etc that you’re searching for and just hit enter. If you’ve just imported your list it may take up to a day before it’s fully indexed. If you’re still not seeing the expected results would you mind reaching out to our support chimps at: http://mailchimp.com/chat so they can help you troubleshoot?

Hi Hugh, To change the color of hyperlinks appearing in the body of your email it pretty quick and easy in the Drag and Drop editor. You’ll find the option under the Design tab and then under Body and finally under Body Link. Here’s a quick video showing the workflow in the app.

I’m not particularly impressed with the new design at this point, I’m finding everything, but only after quite a bit of searching. One thing that it appears has changed is my ability to specify the time I wish to schedule an email to be sent – normally I can set them up for 12 noon to 1 PM, and it now appears that I can’t set anything prior to 3:00 PM. Would appreciate knowing if I’m doing something incorrectly or if this is an actual change.

Hi Jeroen, Just wanted to give you a heads up and let you know that our first API v2 wrappers are now available for PHP, Python, Ruby, and NodeJS – You can find out all the specifics here: http://eepurl.com/CNmE5

(Seems that replicating an earlier campaign as a model for a new campaign is not possible in new the version. I would like to designate a recent campaign done in the old MailChimp as a template to be used in the new MailChimp. Is there a way to do this?)

In the meanwhile producing campaigns would be a lot faster for me if I can use old MailChimp.

Hi Herman, If you go to Campaigns and view the list of campaigns you’ll see next to the campaigns is a combo button that has the word edit next to a down arrow. Just click on that combo button arrow and you’ll see the option to replicate your campaign. Click replicate and you should be all set. If you have additional questions, please feel free to reach out to our support team at: http://mailchimp.com/chat

Hi Pablo, While our Partner API includes the ability to create lists, it is not currently included in the new version of the regular API. This is definitely, the kind of thing that could be abused which is why we’ve left it out and also the reason why the Partner API is very limited.

Hi Rafael, I’m not a programmer, but I’ve gone digging and have some options that may help get you pointed in the right direction. I’d start off here to make sure your call syntax is all correct. Also, while I don’t know the specifics of your situation one of the devs suggested taking a closer look at the .NET wrappers found here as that might give you what you need. Again, that’s just a best guess, but if you’re still not finding what you need, you might want to pop in over at the MailChimp API discussion group.