# Mailchimp API keys: find, create, and use them safely
> Your Mailchimp API key grants full account access, carries no scopes and expires one year after creation. Where to find it, and how to wire it into an agent.
- **URL:** https://www.ad-vertly.ai/post/mailchimp-api-keys
- **Published:** 2026-11-16
- **Author:** Gaurav Singh
---Your Mailchimp API key lives under Profile, then Extras, then API keys. Click Create A Key, name it after the integration that will use it, and copy the whole string including the suffix at the end. Mailchimp shows that string once. It grants full access to your account, so treat it like your password.

Most tutorials stop there. The parts that actually break integrations sit one layer down: the data center suffix that decides your base URL, the fact that a key carries no scopes at all, a one-year expiry Mailchimp added in 2026, and a concurrency limit counted per user instead of per key.

All four get sharper once an agent holds the credential rather than a person. An agent retries in a loop, logs the error body verbatim, and rarely notices that the code it got back means something other than what it says. If that's the setup you're building, the wider picture of [AI marketing agents](https://www.ad-vertly.ai/post/ai-marketing-agents-for-solo-founders) is worth reading alongside this page.

## What a Mailchimp API key actually is

It's a credential string and nothing more. Mailchimp issues 32 characters, a dash, and the data center your account runs in. There's no metadata inside it, no expiry date you can read from it, and no permission list attached to it.

That last part surprises people arriving from other APIs, because a Mailchimp Marketing API key has no scopes. It carries [full access to the account it belongs to](https://mailchimp.com/help/about-api-keys/), which means it can add contacts, delete contacts, edit audiences, create campaigns and read your revenue data. There is no read-only key to hand to a reporting job.

The only permission control sits outside the key. What the key can reach is decided by the role of the user who created it. A key made by an Admin sees everything, a key made by a Manager is narrower, and if you change that person's role later the key's reach changes with it while the key string stays identical.

## How do you create and find your Mailchimp API key?

You need Manager or Admin permissions. Standard and Viewer accounts can't create keys at all, which is the first wall people hit when a client has handed them access but not a role.

1. Sign in to Mailchimp and click your profile icon in the top right.
1. Choose Profile. Older builds label this Account and billing, and the key page is the same either way.
1. Open the Extras menu and select API keys.
1. Click Create A Key, then name it for the thing that will use it. Use Reporting sync or WordPress signup form, never key 2.
1. Copy the full key immediately. After you close the dialog Mailchimp shows only the name and the first four characters.
1. Store it in a secret manager or an environment variable before you wire it into anything.

From that point the key list shows a name and four characters. If you've lost the string you don't recover it, you make a new key and revoke the old one. Admins also see keys other users generated; Managers only see their own.

## Where does the data center suffix go?

The characters after the last dash are your account's data center, and they decide the hostname every request goes to. A key ending in us21 means your base URL is https://us21.api.mailchimp.com/3.0/ and a key ending in us6 means https://us6.api.mailchimp.com/3.0/.

Hand-written clients get this wrong constantly, and neither failure mode says wrong host. You either get a hostname that doesn't resolve, which reads like a network problem, or an authentication failure against the wrong server, which reads like a bad key.

Derive the suffix from the key instead of hardcoding it. Split on the final dash, take the last segment, and build the host from it, so a rotation that moves you between data centers doesn't need a config change. The same discipline applies to any paginated API you wire into an agent, including the [pagination traps in the Search Console API](https://www.ad-vertly.ai/post/google-search-console-api-row-limit).

## What the key grants, and what it refuses to do

Two error codes carry most of the diagnostic weight, and they mean different things. A 401 means the key is invalid or disabled. A 403 means the key is fine but the operation isn't allowed: the creating user lost the role, the plan doesn't cover the feature, or you've hit a throttle.

The 403 branch wastes afternoons. At exceptionally high volume, [Mailchimp's error reference](https://mailchimp.com/marketing/api-concepts/errors/) confirms you can get a 403 with no JSON body at all, and that's a throttling response rather than an authorization one. A client that reads it as an auth failure will rotate a perfectly good key in the middle of an incident.

There's no read-only path either. If you want an agent to read campaign performance without touching your audiences, the only real approximation is a dedicated user with a narrow role, issuing the key from that account. The key inherits whatever that user can do, and nothing else.

## How do you check a key before an agent uses it?

Call the root endpoint. A GET to your version root returns account details including the role attached to the key. It's cheap, it doesn't touch your data, and it answers three questions at once: is the key live, which data center is it on, and what is it allowed to do.

Make that call the first step of any agent run that touches Mailchimp, and fail loudly when the role is narrower than the task needs. One request out of a ten-connection budget is a bargain against discovering a 403 halfway through a contact import.

Log the role once at startup and keep it in your run metadata. If someone tightens a user's permissions six months from now, your logs will show the change before your users do.

## Mailchimp API keys now expire after one year

This is the change most published guides still miss, and it turns a credential problem into a calendar problem.

> Mailchimp Help, About API Keys, updated for the 22 June 2026 change: "Effective June 22, 2026, any new API key you generate will expire 1 year after its creation date. API keys created before June 22, 2026 aren't affected by this change and won't expire."

Read the cut-off carefully, because it creates a mixed fleet. Keys minted before that date run indefinitely. Keys minted after it stop working twelve months later, silently. An integration that worked all year starts returning 401 on a date nobody wrote down.

This is the failure mode an unattended agent handles worst. It gets a 401, retries, gets another 401, then either gives up quietly or escalates a vague error to a human who has to rediscover the expiry rule. Store the creation date next to the key and put the rotation reminder in the same place as the key itself.

If you're wiring several platforms into one agent, that discipline pays off more than once. See [what a full-stack marketing agent actually does](https://www.ad-vertly.ai/post/full-stack-marketing-agent-explained) for the shape of that setup.

## Ten connections is the real rate limit

Most people expect a requests-per-minute ceiling. Mailchimp doesn't publish one. What it enforces is [10 simultaneous connections](https://mailchimp.com/developer/marketing/api-concepts/rate-limits-and-timeouts/), and the limit is per user, not per API key and not per client.

That single sentence catches agent builders out, because the budget is shared with everything else on the account, including the Mailchimp web app open in a browser and every other integration the customer installed. Issuing the agent a second key buys no headroom. Splitting the work across two processes buys none either.

Three more numbers are worth writing down. Individual calls time out at 120 seconds. Batch operations cap at 500 pending requests, with roughly 500 pending batch webhook events. Webhooks have to respond within 10 seconds or the request is cancelled and retried at increasing intervals for 75 minutes.

The batch endpoint is the pressure valve, because Mailchimp runs those operations on its own infrastructure and the request stops holding one of your ten connections while it works. That's why large imports belong there rather than in a parallel loop. And since the Marketing API returns no rate-limit headers, there's no remaining-budget figure to read, so a client can only keep its own concurrency below ten and back off when a 429 arrives. Exponential backoff is the only honest strategy.

## Giving a marketing agent a key without handing over the account

The arithmetic is uncomfortable. A key with no scopes, held by a long-running process, sitting in a config file. If it leaks, the blast radius is the whole account: contacts, audiences, campaigns, revenue data. Five habits cut that down.

- Create a dedicated Mailchimp user for the agent and issue the key there, so revoking the agent doesn't disturb a human's access.
- Give each integration its own key with a name that identifies it. Revocation is permanent, so a shared key means one incident takes out every consumer.
- Keep the key in a secret manager and inject it at runtime. Never paste it into a prompt, a chat transcript, a screenshot or a tool log, and remember that blurring a screenshot isn't redaction.
- Respect the runtime rules Mailchimp states outright: no client-side calls with CORS, no keys inside mobile apps, and OAuth 2.0 if other people will connect their own accounts.
- Put the concurrency limiter inside the agent, because there are no response headers to read.

Know the revoke story in advance too. Revoking a key is permanent and can't be undone, and removing a user from the account deletes every key that user generated. That's a clean offboarding path, and a nasty surprise if that user was the only one who knew the key existed.

If the tooling cost starts to outweigh the value of the integration, the comparison of [Mailchimp alternatives](https://www.ad-vertly.ai/post/mailchimp-alternatives-for-solo-founders) covers how other platforms handle machine access, and [marketing automation workflows](https://www.ad-vertly.ai/post/marketing-automation-for-solo-founders) covers where the keys actually earn their keep.

## The key hygiene checklist

Before an agent goes live with a Mailchimp key, all seven of these should be true.

- One key per integration, named for the integration.
- Key created by a dedicated user whose role matches the job, not by the account owner.
- Creation date stored next to the key, with a rotation reminder before the 12-month expiry.
- Data center suffix derived from the key rather than hardcoded into the base URL.
- Concurrency capped below ten, with every other consumer on the account counted.
- Role read from the root endpoint at startup and written to the run log.
- 401 and 403 handled as different failures, with a bare 403 treated as a throttle.

None of that is exotic. It's the difference between an integration that survives its first year and one that quietly dies on an anniversary nobody remembered.

## Frequently asked questions

### Where do I find my Mailchimp API key?

Click your profile icon, choose Profile, open the Extras menu and select API keys. The page also has a direct address: admin.mailchimp.com/account/api. After you create a key, Mailchimp shows the full string once and then only its name and first four characters.

### Do Mailchimp API keys expire?

Keys generated on or after 22 June 2026 expire one year after their creation date. Keys created before that date don't expire. Store the creation date with the key so a rotation reminder exists before the 401 arrives.

### Can I make a read-only Mailchimp API key?

No. A Marketing API key carries full access to its account and has no scopes or read-only variant. To limit what an integration can do, create a dedicated user with a narrower role and issue the key from that account.

### What is the Mailchimp API rate limit?

There is no published per-minute cap. The enforced limit is 10 simultaneous connections per user, shared across every key and client on that account. Exceeding it returns a 429, and the API sends no rate-limit headers you can read in advance.

### Why does my Mailchimp API key return 403 instead of 401?

A 401 means the key is invalid or disabled. A 403 means the key is valid but the operation isn't allowed, usually because the creating user's role changed or the plan doesn't cover the feature. A bare 403 with no response body at high volume is a throttle.

## Tools from the same team

Each one removes a manual step from marketing work.

- [adextract - ad intelligence](https://app.adextract.co/connect?utm_source=ad_vertly_blog&utm_medium=cta&utm_campaign=mailchimp-api-keys)
- [imperfectly - writing in your voice](https://imperfectly.app/?utm_source=ad_vertly_blog&utm_medium=cta&utm_campaign=mailchimp-api-keys)
- [cobnut - content, organised](https://getcobnut.com/?utm_source=ad_vertly_blog&utm_medium=cta&utm_campaign=mailchimp-api-keys)
