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,

Supporting Phil Sturgeon’s Charity Ride

Dear Reader,

Those of you who know me know that I run Nomad PHP. In June, we had my friend Phil Sturgeon speak on the PHP framework Laravel. Nomad PHP pays all of it’s speakers 1/2 of each ticket sold. That amount however, did not go far enough in helping Phil reach his goal to raise $7,000 as he participates in the “Braking AIDS Ride”.

So, to help Phil get closer to meeting his goal, I’m going to make this offer. If you did not see Phil’s talk, “Laravel 4: Yet Another Framework… but different” and you wanted to see it, or you just want to help Phil make a difference in the fight against AIDS, donate $10 or more to Phil’s ride and I will give you access to the recording of his talk.

Here’s how this is going to work. DON’T SEND ME ANY MONEY. Go to this link and make a donation. Then, forward me the email you get from the site confirming your donation. (Remove any sensitive data, I just need to see the date, amount, and confirm it came from them)

I will then send you a link and a password that you can use to watch Phil’s talk as many times as you like.

If you saw Phil’s talk and you just want to help him reach his goal, that’s cool too, he has a list of offers on his blog post to entice you.

Until next time,
I <3 |<

p.s. Could you do us a favor and tweet this around to your friends? We’d all appreciate it. :)