Mailchimp API

Frequently Asked Questions

1. I need Help, where can I get Support??
2. I ran listSubscribe() and no one was added to my list!
3. Is this thing on? Are there any API stats I can see?
4. What's the deal with datacenter-specific API endpoints/URLs?
5. Are there any "best practice" guidelines for integrators or folks developing around the API?
6. Are there connection limits, throttling, rate limiting, etc?
7. I'm worried about the reliabilty of something run by a chimp!
8. How do you handle downtime?

1. I need Help, where can I get Support??

Glad you asked - support info is here

 

2. I ran listSubscribe() and no one was added to my list!

There is roughly a 110% chance that you've not looked for the Confirmation Email and clicked the confirmation link in it. There is a significantly lower chance that it got caught in a spam/junk box or filter, so check those, too.

 

3. Is this thing on? Are there any API stats I can see?

Yup, sure are! We have statistics on API usage broken down by User and IP address. While most of that is for our internal use, some of the data is available to you under your Account API page in our web app.

 

4. What's the deal with datacenter-specific API endpoints/URLs?

We grew, a lot! There's a full recap of the reasons and impact here.

 

5. Are there any "best practice" guidelines for integrators or folks developing around the API?

Sure, why not, let's give this a shot:

• Don't use the login() function for anything. Users can very easily grab their API key if you give them a link to this page: http://admin.mailchimp.com/account/api-key-popup
• Consider caching some values that are often used and rarely changed. For example, instead of calling lists() and cycling through to match a name or web_id, have your user select the list or lists to use when they are configuring, then save the list_id for later use.
• If you are syncing things up, make sure you have looked over our Syncing Database Changes from You to Mailchimp and Syncing Database Changes from Mailchimp to You write-ups.
• Be aware of the connection limits and our reliability statements below.

 

6. Are there connection limits, throttling, rate limiting, etc?

We currently implement Connection Limits and Rate Limit throttling -

Connection Limits

Don't worry too much, they are pretty high - 10 simultaneous connections per IP address (yours) per server (ours). You have to be trying really hard to hit those. If you do, we will be returning a normal error message, so you will have every opportunity to handle that gracefully in your applications. Note: currently there are no options to raise that limit on a per customer basis.

Rate Limit Throttling

We have worked very hard to ensure that this will not affect typical usage, even if yours is pretty high - even then, nothing will actually fail, we will just slow you down. As you make calls to the API, we will be looking at your average calls per second (c/s) over the previous 5 minute period. Here is what will happen:

• over 3c/s and we add a 2 second delay
• over 5c/s and we add a 4 second delay
• over 7c/s and we add a 5 second delay

Those delays will, of course, be added before we execute your call and return its results. As your average drops below those thresholds, the delays will be removed.

It should be pretty rare to have either the Connection Limits or Throttling affect you unless you are trying to be abusive or have some code that is... not very well thought out. If you fall into the latter case, see the use-case information below, or contact us and we'll be happy to help. Note that we also monitor how often these limits are hit and adjust things accordingly.

 

7. I'm worried about the reliabilty of something run by a chimp!

Fair enough. First, if you are cool with just flying by the seat of your pants, then you will be happy to hear that we have 99.9% uptime.

Still reading? Good. The fact of the matter is that everyone has outages, unplanned downtime, and the such on occasion - it's simply a fact of life, especially when dealing with the intertubes and the bazillion services out there you may connect to. If you are serious about caring about potential outages of partner systems you work with, then we suggest you have some method of running calls through some sort of queuing system so that you can retry any failures. Obviously that also means that you need to be doing good error checking in your code as well.

 

7. How do you handle downtime?

First, know that we've never taken the API offline unless the main web app also had to be taken down - when we know there will be downtime it will be Tweeted via our @mailchimp account (and probably re-tweeted via @mailchimp_api). There's also a good chance of a blog post, an in-app messages when you login, and via the Announcement group. Typically the only time that happens is when we do releases that require major database changes, though those typically don't affect an account for too terribly long.

Other than planned downtime, the API reliability tends to directly follow the app's since they are generally using the same resources. As stated above, we have 99.9% uptime, though as with most things, there are occasional bumps or slow downs due to load issues, but even those aren't common. We also use DNS load balancing, so if you are pinned to an app server due to your DNS not respecting our TTLs, you could have issues if an app server in our clusters goes down. Regardless, any time unexpected downtime occurs, information is typically disseminated via the @mailchimp twitter account.