A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Mailchimp API is how an app or AI agent works with a Mailchimp account: adding and updating contacts in an audience, creating and sending campaigns, running automations, and reading how sends performed. Access is granted through an API key or an OAuth 2.0 token, and either one carries the full access of the account it belongs to, because Mailchimp grants access at the account level rather than per area. Mailchimp can also push events to a webhook when something happens in an audience, like a contact subscribing or unsubscribing.
How an app or AI agent connects to Mailchimp determines what it can reach. There is a route for making calls and a route for receiving events, each governed by the key or token behind it.
The Marketing API answers at https://
Mailchimp POSTs form-encoded event data to a receiver URL registered on an audience. Each event carries a type, like subscribe or unsubscribe, a fired_at timestamp, and a data object. Webhooks require a Standard or Premium plan to enable.
An API key authenticates a first-party call to the account that issued it. The key ends in a data-center suffix, like -us19, which sets the subdomain a call goes to. It is sent through HTTP Basic auth, with any username and the key as the password, or as a Bearer token, and it carries the full access of the account, not a narrowed scope.
OAuth 2.0 is for connecting to a Mailchimp account an app does not own. A user authorizes the app at login.mailchimp.com, and the app exchanges the returned code for an access token, then reads the account's data center from the metadata endpoint. There are no scopes to choose: authorizing grants the app account-level access, and the token does not expire unless the user revokes it.
The Mailchimp API is split into areas an agent can act on, like audiences, contacts, campaigns, automations, templates, reports, and ecommerce stores. Each area has its own methods, and a key or token reaches every area its account can, because access is granted at the account level rather than per area.
List the account's audiences, read one, create an audience, update its settings, and remove one.
List and read contacts in an audience, add a contact, add or update one, change a contact, and archive or permanently delete one.
List and create segments in an audience, and list and create the merge fields that store contact attributes.
List, read, create, update, and delete campaigns, set their content, send a test, and schedule or send them.
List and read classic automations, and start or pause all the emails in one.
List, read, create, update, and delete the templates that lay out a campaign.
Read campaign performance reports across the account and for a single campaign.
List, read, create, update, and delete connected stores, and add the orders that drive purchase-based marketing.
List and create the webhooks on an audience that push events to a receiver URL.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Audiences (lists)List the account's audiences, read one, create an audience, update its settings, and remove one.5 | ||||||
| GET | /lists | Get information about all audiences (lists) in the account. | read | — | Current | |
Mailchimp grants account-level access, so any valid key or OAuth token can call this; there is no per-endpoint scope. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /lists/{list_id} | Get information about a specific audience. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /lists | Create a new audience in the account. | write | — | Current | |
Account-level access; any key or token can write. An account has a cap on how many audiences it can hold, set by plan. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /lists/{list_id} | Update the settings for a specific audience. | write | — | Current | |
Account-level access; no per-endpoint scope. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /lists/{list_id} | Delete an audience from the account. | write | — | Current | |
Removes the audience and its contacts. Account-level access; no per-endpoint scope. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Contacts (list members)List and read contacts in an audience, add a contact, add or update one, change a contact, and archive or permanently delete one.7 | ||||||
| GET | /lists/{list_id}/members | List the contacts in an audience. | read | — | Current | |
Returns contacts' email addresses and profile data. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /lists/{list_id}/members/{subscriber_hash} | Get information about a specific contact, addressed by the MD5 hash of their lowercased email. | read | — | Current | |
The subscriber_hash is the MD5 hash of the lowercased email address. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /lists/{list_id}/members | Add a new contact to an audience. | write | — | Current | |
Fails if the contact already exists; the add-or-update method below is idempotent. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /lists/{list_id}/members/{subscriber_hash} | Add a contact, or update one if it already exists in the audience. | write | — | Current | |
The idempotent way to sync a contact. A status of subscribed counts as an opt-in. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook event subscribeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /lists/{list_id}/members/{subscriber_hash} | Update a contact in an audience. | write | — | Current | |
Setting status to unsubscribed unsubscribes the contact. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook event profileRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /lists/{list_id}/members/{subscriber_hash} | Archive a contact, removing them from the audience while keeping their history. | write | — | Current | |
Archiving is reversible; the permanent-delete action below is not. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /lists/{list_id}/members/{subscriber_hash}/actions/delete-permanent | Permanently delete a contact and all personally identifiable information for them. | write | — | Current | |
Irreversible, and the same email cannot be re-imported afterward. Account-level access; no per-endpoint scope. Acts onlist member Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Segments & merge fieldsList and create segments in an audience, and list and create the merge fields that store contact attributes.4 | ||||||
| GET | /lists/{list_id}/segments | Get information about all segments in an audience. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts onsegment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /lists/{list_id}/segments | Create a new segment in an audience. | write | — | Current | |
A segment can be a saved set of conditions or a fixed (static) list of contacts. Account-level access; no per-endpoint scope. Acts onsegment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /lists/{list_id}/merge-fields | Get a list of all merge fields for an audience. | read | — | Current | |
Merge fields are the columns that store contact attributes, like first name. Account-level access; no per-endpoint scope. Acts onmerge field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /lists/{list_id}/merge-fields | Add a new merge field for an audience. | write | — | Current | |
Account-level access; no per-endpoint scope. Acts onmerge field Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CampaignsList, read, create, update, and delete campaigns, set their content, send a test, and schedule or send them.7 | ||||||
| GET | /campaigns | Get all campaigns in the account. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /campaigns/{campaign_id} | Get information about a specific campaign. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /campaigns | Create a new campaign. | write | — | Current | |
Creates the campaign as a draft; content and sending are separate calls. Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /campaigns/{campaign_id}/content | Set the HTML, plain-text, or template content for a campaign. | write | — | Current | |
Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /campaigns/{campaign_id}/actions/test | Send a test email of a campaign to chosen recipients. | write | — | Current | |
Emails only the test recipients, not the audience. Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /campaigns/{campaign_id}/actions/schedule | Schedule a campaign to send at a chosen time. | write | — | Current | |
The scheduled send still emails the audience when it fires. Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /campaigns/{campaign_id}/actions/send | Send a campaign immediately to its audience. | write | — | Current | |
Emails real contacts and cannot be recalled once it begins. Account-level access; no per-endpoint scope. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook event campaignRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AutomationsList and read classic automations, and start or pause all the emails in one.3 | ||||||
| GET | /automations | Get a summary of the account's classic automations. | read | — | Current | |
Covers classic automations; newer Customer Journeys are managed in the app. Account-level access; no per-endpoint scope. Acts onautomation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /automations/{workflow_id}/actions/start-all-emails | Start all emails in a classic automation workflow. | write | — | Current | |
Resumes sending to contacts who enter the workflow. Account-level access; no per-endpoint scope. Acts onautomation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /automations/{workflow_id}/actions/pause-all-emails | Pause all emails in a classic automation workflow. | write | — | Current | |
Account-level access; no per-endpoint scope. Acts onautomation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TemplatesList, read, create, update, and delete the templates that lay out a campaign.3 | ||||||
| GET | /templates | Get a list of an account's available templates. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /templates | Create a new template for the account. | write | — | Current | |
Only classic templates are supported here. Account-level access; no per-endpoint scope. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /templates/{template_id} | Delete a specific template. | write | — | Current | |
Account-level access; no per-endpoint scope. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReportsRead campaign performance reports across the account and for a single campaign.2 | ||||||
| GET | /reports | Get campaign reports across the account. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts onreport Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /reports/{campaign_id} | Get the report details for a specific sent campaign. | read | — | Current | |
Reports include opens, clicks, and bounces by recipient. Account-level access; no per-endpoint scope. Acts onreport Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Ecommerce storesList, read, create, update, and delete connected stores, and add the orders that drive purchase-based marketing.3 | ||||||
| GET | /ecommerce/stores | Get information about all connected ecommerce stores. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /ecommerce/stores | Add a new ecommerce store to the account. | write | — | Current | |
A store links purchase data to an audience. Account-level access; no per-endpoint scope. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /ecommerce/stores/{store_id}/orders | Add an order to a store, which drives purchase-based marketing. | write | — | Current | |
An order's campaign_id is overwritten to match Mailchimp's attribution model. Account-level access; no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList and create the webhooks on an audience that push events to a receiver URL.2 | ||||||
| GET | /lists/{list_id}/webhooks | List the webhooks registered on an audience. | read | — | Current | |
Account-level access; no per-endpoint scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /lists/{list_id}/webhooks | Create a webhook on an audience for the chosen event types. | write | — | Current | |
The events object toggles which event types fire, like subscribe and unsubscribe. Account-level access; no per-endpoint scope. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mailchimp can notify an app or AI agent when something happens in an audience, like a contact subscribing or unsubscribing, instead of the app repeatedly asking. Mailchimp posts the event to a webhook URL that has been registered on a list for the chosen event types.
| Event | What it signals | Triggered by |
|---|---|---|
subscribe | Fires when a contact subscribes to an audience. | /lists/{list_id}/members/lists/{list_id}/members/{subscriber_hash} |
unsubscribe | Fires when a contact unsubscribes from an audience, whether they opt out or are removed. | /lists/{list_id}/members/{subscriber_hash} |
profile | Fires when a contact's profile is updated, like a changed merge field value. | /lists/{list_id}/members/{subscriber_hash}/lists/{list_id}/members/{subscriber_hash} |
upemail | Fires when a contact changes the email address on their record. | In-app only |
cleaned | Fires when an address is cleaned from the audience, after it hard-bounces or is flagged for abuse. | In-app only |
campaign | Fires when a campaign finishes sending to the audience. | /campaigns/{campaign_id}/actions/send |
Mailchimp limits how many requests an app or AI agent can run at once, through a cap on simultaneous connections per key rather than a request-per-second quota.
Mailchimp meters by how many requests run at once, not by a per-second or per-method quota. The Marketing API allows 10 simultaneous connections per API key, and a request over that returns HTTP 429. A separate cap holds 500 pending webhook deliveries before further events are dropped, which also surfaces as a 429. Long-running bulk work is meant to go through the batch-operations endpoint rather than many parallel calls.
List endpoints page through offset and count query parameters, where count sets the page size, up to 1000, and offset sets where the page starts. A total_items field in each response gives the full count so a caller knows when to stop. The fields and exclude_fields parameters trim the response to only the parts needed, which keeps large list responses small.
A list endpoint returns at most 1000 items per page through the count parameter. Bulk changes across many records are meant to run through the batch-operations endpoint, which queues the work and returns the results as a downloadable file rather than in the response body.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request / Invalid Resource / JSON Parse Exception | The request could not be processed: it was malformed, a field failed validation, or the JSON body could not be parsed. | Read the detail field and the per-field errors array, correct the request, and resend. |
| 401 | API Key Invalid | The API key is missing, invalid, or disabled, or the OAuth token is not valid. | Send a valid key or token, and confirm the call is going to the right data center subdomain. |
| 403 | Forbidden | Access is denied because of the user's account permissions, a deactivated account, or a pricing-plan restriction on the feature. | Confirm the account has the permission and plan the feature needs. |
| 404 | Resource Not Found | The requested resource does not exist or is not visible to this account. | Check the path and the resource id, such as the list_id or subscriber_hash. |
| 405 | Method Not Allowed | The endpoint does not support the HTTP method used in the request. | Use the method the endpoint documents, such as PATCH rather than PUT to update. |
| 422 | Invalid Method Override | The X-HTTP-Method-Override header was used on a request that was not a POST, which is the only method it works with. | Only send the method-override header on POST requests. |
| 429 | Too Many Requests | A limit was hit: either the 10 simultaneous connections per key, or the cap of 500 pending webhook deliveries. | Lower how many requests run at once, then retry after the in-flight ones finish. |
| 500 | Internal Server Error | An error occurred on Mailchimp's side. | Retry after a short wait, and contact Mailchimp support if it persists. |
Mailchimp runs a single current version of its Marketing API, 3.0, and ships dated release notes for new endpoints and behavior changes rather than minting new version numbers.
The Marketing API runs one current version, 3.0, in every call path, like /3.0/lists. Mailchimp does not issue new version numbers for changes; instead it publishes dated release notes when endpoints or behavior change, and an integration tracks those notes rather than pinning a version.
Mailchimp added alternative Audiences endpoints that let a contact be added with just an SMS number, without an email address, which the standard members endpoints had required.
Mailchimp began overwriting the campaign_id and outreach_id fields on ecommerce orders so they align with Mailchimp's native attribution model, and advised developers to drop any custom logic that set those fields.
There is one current version to call, so an integration tracks the release notes rather than pinning a version.
Mailchimp release notes ↗Bollard AI sits between a team's AI agents and Mailchimp. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.