Skip to content

Mailchimp API v3 and Address fields

Freddie_OGDear Reader,

I love MailChimp. I mean I seriously love it. I’m not a big fan of SaaS vendors. I think that most of them are just obvious ideas that someone found a way to shove behind a paywall. But I love MailChimp.

One of the reasons I love it is that it seems to have been built for developers. Everything about it seems to be geared towards developers. This includes their API. I’ve been using v2 of their API in scrips for a few years now and it was just so easy to work with. Their PHP wrapper for it was one of the easiest to use API wrappers I’ve used.

Enter API V3

Recently, (March is recently, right?) they announced v3 of their API. It was “RESTful”. What used to be an absolute breeze to use in v2 has now become a laborious chore to use. It doesn’t help that they don’t bother to release sample code in PHP, if you aren’t a Python or Ruby developer, you have to figure it out on your own.

So that is what I did. I sat down with Guzzle and beat it into submission. While you can still do everything you could do before, to blindly adhere to the principals of REST, they have made retrieving something as simple as all of the information about a single email address 3-4 calls. Complexity for the sake of “doing it right”. (Because there is no way this is actually easier to use, but REST purists will love it.)

Address the issue

One area of change was how the merge fields work. Now this isn’t actually harder than v2, because this was the weak point in v2. However, using their ADDRESS type merge field, I found something very interesting.

The MailChimp Address field is actually made up of 6 different properties.

  • Address Line 1 (addr1)
  • Address Line 2 (addr2)
  • City (city)
  • State (state)
  • Zip Code (zipcode)
  • Country (country)

It’s not terribly difficult to work with from the API…unless. I found an interesting anomaly in the API. Your address lines cannot contain 2 consecutive spaces. Dang near drove me up the wall because it doesn’t tell you that this is a problem, or even which line in the address field has a problem. The error message that comes back simply tells you to enter a valid address.


Ok, if you are using the MailChimp API v3 and you are using PHP, Guzzle is your friend. Also, make sure you strip out any double spaces. Here is how I did it.

$addr1 = filter_var($payload["addr1"],FILTER_SANITIZE_STRING);
$mcRecord->merge_fields->ADDRESS->addr1 = strtr($addr1,['  '=>' ']);

Personally, I believe that this behavior is an artifact of how Mailchimp’s importer works. If you read the docs, they use double spaces to split apart the pieces of an address. Since I was assigning a string with double spaces to a single field. I think the API was choking on that and that is why it spit it back out at me. Of course a helpful error message or even a blog post mentioning this rule would have saved me some frustration.

Still, Mailchimp beats everything else, hands down. Still a fan, even if a bit frustrated.

UPDATE: See the comment below, Pete addresses the issues. (Thank you Pete!) :)

Until next time,

5 thoughts on “Mailchimp API v3 and Address fields

  1. Hi, Cal! I’m sorry to hear that you had a rough time with API v3; thanks for blogging your experience! I thought I’d address some of your comments!

    We are definitely not trying to make v3.0 more difficult and we actually cut some REST corners for ease of use and have found our internal use of the API to be significantly easier in v3.0 than previous versions. It did require significant rewrites in some cases, though. That said, we are erring on the side of less data in each response. Once that data is in a response, we can’t ever remove it. v2.0 responses had a lot of data that many people didn’t need and in many cases, producing that data made the calls significantly slower.

    We’d love to hear more details about your use case — it may be that we overlooked something or there could be a different approach that would work more easily. Please feel free to reach out via email to me or apihelp at mailchimp.

    The address issue has actually existed for a long time and has to do with the way we store that data on the backend (in a single two-space-delimited string). In 2.0 you can even pass a two-space-deliminted-string, but we’re trying to get away from that usage. I’ll get the unhelpful error message for that case added to our bug tracker, though. It might even work for us to convert double spaces on the way in, but I’ll have to look and see how the rest of the app handles that scenario.

    Thanks for taking the time to write this all out! If you have any other feedback, please let us know!

Comments are closed.