403, linked to a different datacenter
How you'll know: The key is new and correct, but every call is refused.
Fix: The host doesn't match the key's prefix. Change the URL (or the plugin's server field) to the code after the dash in your key.
A Mailchimp API key takes about a minute to create, and you only get to copy it once. The part that trips people up comes after: the key ends in a code like -us6, and that code decides which server every API call has to go to.
Create the key: click your profile icon, choose Profile, open the Extras menu and pick API keys, then Create A Key.
Profile icon › Profile › Extras › API keys › Create A KeyCopy it now. After you close the dialog Mailchimp only shows the key's name and first four characters. Lose it and you make a new one.
Note the ending. The letters and number after the last dash (us6, us21) are your server prefix. Calls go to https://us6.api.mailchimp.com/3.0/, with your prefix in place of us6.
You need Manager permissions or higher in the Mailchimp account.
The profile icon is at the top right of Mailchimp. Older guides call this area Account & billing. The key lives in the same place.
This page lists the keys you've made, by name and first four characters. Admins also see keys other users created.
Watch for: any Mandrill or Transactional key option. That's a different key for a different product. For audiences and campaigns you want Create A Key.
Call it "WordPress signup form" or "CRM sync", not "key 2". When you need to revoke one later, the name is all you'll have to go on.
Paste it straight into the tool that needs it, or into a password manager. Never paste it into front-end code or a mobile app: a Mailchimp key gives full access to the account, and there are no read-only keys.
Mailchimp runs accounts on separate data centers, and each key is tied to one. The prefix after the dash in your key, such as us6, is that data center. You'll also see it in your browser's address bar when you're logged in (us6.admin.mailchimp.com). Plugins that ask for a "dc" or "server" field want exactly that code.
Send a call to the wrong host and Mailchimp refuses it. Point a -us6 key at the bare api.mailchimp.com and it answers 403 Forbidden: The API key provided is linked to a different datacenter. Use your own prefix and that error goes away.
For raw HTTP, send the key with Basic authentication (any word as the username, the key as the password) or as a Bearer token in the Authorization header. Call the Ping endpoint at /3.0/ping first: a healthy answer means the key and prefix both work.
How you'll know: The key is new and correct, but every call is refused.
Fix: The host doesn't match the key's prefix. Change the URL (or the plugin's server field) to the code after the dash in your key.
How you'll know: It worked last month and now fails on the right host.
Fix: The key was revoked, or mistyped when pasted. Keys also disappear when the user who created them is removed from the account, a common surprise after a staff change. Create a new key under a user who's staying and swap it in.
How you'll know: Reading works, but creating campaigns or changing settings is refused.
Fix: A key can only do what its creator's user role allows. Make the key under an Admin user if the integration needs to change more than contacts.
How you'll know: Bulk imports fail part way through.
Fix: The Marketing API allows 10 simultaneous connections per user, across all that user's keys. Queue the calls, or send large jobs through the Batch endpoint.
How you'll know: A CORS error in your web page's console.
Fix: Mailchimp blocks browser calls to the Marketing API on purpose. Make the call from your server, or use an embedded Mailchimp signup form for simple sign-ups.
Mandrill is now Mailchimp Transactional. It sends a single email triggered by something a person just did, such as an order receipt, a password reset or a shipping notice, through its own API or SMTP. It's billed separately from your Mailchimp plan and uses its own keys, so a Marketing API key won't work against it. Sending receipts as regular campaigns means anyone who unsubscribed from marketing stops getting their receipts too.
Webhooks run the other way: Mailchimp calls your URL when something changes in an audience, such as a subscribe, an unsubscribe, a changed email address or a campaign finishing. Set one up under Audience, Manage Audience, Settings, Webhooks. Your endpoint has 10 seconds to answer before Mailchimp retries, the body arrives form-encoded rather than as JSON, and the signing secret is shown once when you save.
n-frames builds the integrations behind these keys: contact and tag syncs from a CRM or store, transactional sends wired from the event in your own system, and webhook receivers that keep both sides in step, with alerts when a key stops working. More on what connects to what on our Mailchimp integrations page.
Click your profile icon, choose Profile, then Extras, then API keys. You can't view an existing key in full there, only its name and first four characters, so if you don't have it saved, click Create A Key and make a new one.
No. Mandrill, now called Mailchimp Transactional, is a separate product for one-to-one triggered email. It has its own app at mandrillapp.com, its own API keys and its own billing, on top of a Mailchimp Standard plan or higher.
An email sent to one person because of something they just did: a receipt after a purchase, a password reset, a booking confirmation. A campaign goes to a list or segment on a schedule you choose.
Yes. Audience webhooks call your URL on subscribes, unsubscribes, profile and email changes, cleaned addresses and campaign sends. You create them in the audience's settings or through the API.
Yes, API access comes with every Mailchimp account at no extra charge, with your plan's features and the 10-connection limit applying. Transactional email is the exception: it's billed separately by volume.
The code after the last dash, such as us6. It names the data center your account is on, and API calls have to go to that host, for example us6.api.mailchimp.com. The wrong host returns a 403.
No. Every key has the full access of the user who created it. To limit what an integration can do, create the key under a user with a lower role, keeping in mind the key is revoked if that user is removed.