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, but 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?

Indeed:

  • For platform integrations (IE: you have a platform, not a plugin/add-on being distributed), consider using OAuth2. Alternately, users can easily grab their API key if you give them a link to this page: https://admin.mailchimp.com/account/api-key-popup
  • Cache values that are used often and rarely changed and pay attention to the number of calls that code you are working on is going to generate. Not doing this in your integrations or plugins will cause users to be warned or even shut down for abusing the API. Some firm examples:
    • For simple subscribitions, cache the values required from methods like lists(), listInterestGroupings(), and listMergeVars() and provide a setup area to allow the user to modify the cached values.
    • Many, many methods should not be called more than a handful of times per day—some examples are listStaticSegments(), campaigns(), campaignMembers(), and all Campaign Stats type methods
    • Keep your calls in check with your list size. For example, making calls to methods such as listSubscribe(), listBatchSubscribe(), listMembers(), listStaticSegmentAdd(), listStaticSegmentAdd(), listStaticSegmentMembersAdd(), listMemberInfo(), listStaticSegmentReset() that exceed 25% of your list size will almost always be unnecessary and look like abuse.
    • Keep your campaign creating and sending in check with how our service is intended to be used. Specifically, more than about 75 calls a day (and that's high) to campaignCreate(), campaignSendNow(), campaignSchedule() are going to look really fishy. If you are doing that, you likely should be using a transactional-email solution, not a bulk email solution.
  • 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.
  • Let us know who you are: use a custom User-agent so we can better identify your integration in our logs and register in our Connect Directory
  • Be aware of the connection limits and our reliability statements below.
6. Are there connection limits, throttling, rate limiting, etc?

Yes:

Connection Limits

Don't worry too much, they are pretty high—10 simultaneous connections per IP address (yours) per user account (in our systems, which also means per datacenter). You have to be trying pretty 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 five-minute period. Here's 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.

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