The Mailchimp Marketing API provides programmatic access to Mailchimp data and functionality, allowing developers to build custom features to do things like sync email activity and campaign analytics with their database, manage audiences and campaigns, and more.

To use the Marketing API, you need a Mailchimp account. What you can do with the API depends on whatlevel of Mailchimp plan you have. Once you have an account and are logged in, you canget an API key andbegin making calls to the API.

Using Mailchimp

Whether you’re managing your own campaigns, providing Mailchimp services to your customers or clients, or writing a mobile app, the Mailchimp Marketing API has features to manage and sync your contact data.

Audiences are at the core of sending campaigns with Mailchimp. You can use the Marketing API toset up an audience and add contacts to that audience; you can then organize those contacts withtags or segment them by activity withevents.

The Marketing API can also be a source of data for your application.Webhooks collect and transmit information about your audience to you in near real time. And if you’re selling products on an external store, you can integrate your audience behavior using Mailchimp’s E-commerce features.

You can also use the Marketing API to  handle data in different ways for different purposes. If you are syncing a large amount of data with Mailchimp, you can usebatches to avoid hitting the API request limits. For building integrations that let other users access data from their own Mailchimp accounts, you shouldauthenticate with OAuth 2. And if you’re developing an app for iOS or Android, theMobile SDK provides an easy way to work with a mobile-focused subset of the Marketing API’s functionality.

API versions

The Marketing API is currently on version 3.0.

We also support a single-purpose Export API version 1.0, which provides API support for some of ouraccount export functionality. See theExport API documentation for full details.

The first versions of the Marketing API, versions 1.1, 1.2, and 1.3, are no longer available.

The previous version 2.0 has not been shut off, but is deprecated and unsupported. We’ll announce shut off dates in advance, but we recommend migrating to version 3.0 since version 2.0 is not regularly tested or maintained.

The Marketing API generally follows REST conventions, with some deviations. 

• Resources are typically nouns likesubscribers orcampaigns.

• Subresourcescan be multiply nested under resources.

• Actions are usually represented byHTTP methods. Actions that do not correspond to HTTP methods are collected under anactions/ subresource.

• Responses use the generic JSON content type.

We use theOpenAPI Specification (formerly known as Swagger) to describe each endpoint.The API self-description also contains type information to help you error-check your requests.

The root url for the API ishttps://<dc>.api.mailchimp.com/3.0/. The<dc> part of the URL corresponds to the data center for your account. For example, if the data center for your account isus6, all API endpoints for your account are available relative tohttps://us6.api.mailchimp.com/3.0/.

There are a few ways to find your data center. It’s the first part of the URL you see in theAPI keys section of your account; if the URL ishttps://us6.mailchimp.com/account/api/, then the data center subdomain isus6. It’s also appended to your API key in the form key-dc; if your API key is0123456789abcdef0123456789abcde-us6, then the data center subdomain isus6. And finally, if you’re connecting via OAuth 2, you can find the data center associated with the token via the OAuth Metadata endpoint; for more information, see theOAuth guide.

For more details on how to query Marketing API endpoints, seeMethods and Parameters. For troubleshooting API calls, see theErrors docs.

You can authenticate requests using either your API key or an OAuth access token, depending on your use case. You should use an API key if you’re writing code that tightly couplesyour application data toyour Mailchimp account data; if you ever need to accesssomeone else’s Mailchimp account data, you should use OAuth 2.

For more information on the Mailchimp OAuth 2 flow, seeAccess Data on Behalf of Other Users with OAuth 2.

If you’re integrating with the Marketing API using one of theofficial client libraries, you won’t need to worry about the implementation details for authentication.

Authenticate with an API key or OAuth 2 token

API keys and OAuth 2 tokens can be used to make authenticated requests the same way. We’ll refer to both as tokens.

You can either use HTTP Basic Authentication or Bearer Authentication.

HTTP Basic Authentication:

curl --request GET \--url 'https://<dc>.api.mailchimp.com/3.0/' \--user 'anystring:TOKEN

Bearer Authentication:

--url 'https://<dc>.api.mailchimp.com/3.0/' \--header "Authorization: Bearer <TOKEN>"

User API access

API authentication is tied to the user that created the API key or authorized the OAuth2 app. If the user is removed from the account, that authentication token will be revoked.

API access is also limited by theuser level (role) of the authorizing user. The role is not fixed, and can change over time. You can check the role for an API key using theAPI Root endpoint, and see the restrictions inthis chart. Attempts to perform an API action that aren’t permitted for the role will return a403 error. When creating an API key or authorizing an app, we recommend using an admin user when possible. OAuth integrators may want to inform the user if the application won’t work at their user level.

To improve the experience for all our users, we impose some limits on API requests. These limits prevent a single user from making too many expensive calls at once. Exceeding the limits can result in your API access being disabled, so be cognizant of the quantity and complexity of your requests. Currently there are no options to raise the limit on a per-customer basis.

Throttling

The Marketing API has a limit of 10 simultaneous connections. You’ll receive a429 error if you reach the limit. At exceptionally high volumes, you may receive an HTTP 429 or 403 without a JSON body.

We recommend that you cache frequently accessed values that do not change often in your application’s data store. This will prevent your application from bumping up against the throttling limitations and will likely provide faster access to that data.

Stream timeouts

The Marketing API has a 120-second timeout on API calls. You may see this type of timeout after you’ve made a network socket connection and are already sending and receiving data.

Response times are dependent on the complexity of your request and the general load across Mailchimp. Some endpoints in the Marketing API return values that are large and slow to calculate. Once you know what data you need, use thepagination and partial response capabilities to request only what is essential to you.