Mailchimp Developer Homepage

Fundamentals

The basics

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 what level of Mailchimp plan you have. Once you have an account and are logged in, you can get an API key and begin making calls to the API.

anchor to using-mailchimpUsing 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 to set up an audience and add contacts to that audience; you can then organize those contacts with tags or segment them by activity with events.

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 use batches to avoid hitting the API request limits. For building integrations that let other users access data from their own Mailchimp accounts, you should authenticate with OAuth 2. And if you’re developing an app for iOS or Android, the Mobile SDK provides an easy way to work with a mobile-focused subset of the Marketing API’s functionality.

anchor to api-versionsAPI 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 our account export functionality.

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.

API structure

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

  • Resources are typically nouns like subscribers or campaigns.

  • Subresources can be multiply nested under resources.

  • Actions are usually represented by HTTP methods. Actions that do not correspond to HTTP methods are collected under an actions/ subresource.

  • Responses use the generic JSON content type.

We use the OpenAPI 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 directory for the API https://<dc>.api.mailchimp.com/3.0/ includes a map of all available resources and their subresources. The <dc> part of the URL corresponds to the data center for your account. For example, if the data center for your account is us6, all API endpoints for your account are available at https://us6.api.mailchimp.com/3.0/.

Note: You will see the <dc> placeholder or an actual data center subdomain in examples throughout this documentation. Either way, make sure to replace it in your code with the data center subdomain for your account, or your request may generate an error.

For more details on how to query Marketing API endpoints, see Methods and Parameters. For troubleshooting API calls, see the Errors docs.

Connecting to the API

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 couples your application data to your Mailchimp account data; if you ever need to access someone else’s Mailchimp account data, you should use OAuth 2.

If you’re integrating with the Marketing API using one of the official client libraries, you won’t need to worry about the implementation details for either authentication method. If, however, you’re writing your own integration, you’ll need to know how to authenticate with your chosen method.

anchor to authenticate-with-an-api-keyAuthenticate with an API key

To make an authenticated request using your API key, use HTTP basic authentication.

Authenticate with an API key

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

The Marketing API lets you use any string as the username in the user:password portion of the HTTP basic authentication request. Use your API key as the password string (after the colon) in that portion of the request.

Since the username provided in the request is not meaningful, the role assigned to the user who generated the API key determines endpoint access. If you are denied access and you receive a 403 error code, you can use the API Root endpoint to check the user’s role. If the user role associated with an API key changes, the permissions of the API key will change along with that user role. See Manage User Levels in Your Account to learn more about user-level permissions.

Note: You are responsible for the security of your API key; we recommend that you store it in a secure location on your server. Because of the potential security risks associated with exposing your API key, Mailchimp does not support client-side implementation of our API using CORS requests.

anchor to authenticate-with-oauth-2Authenticate with OAuth 2

To make an authenticated request using OAuth 2, send an authorization header along with your request.

Authenticate with OAuth 2

cURL
--url 'https://<dc>.api.mailchimp.com/3.0/' \
--header "Authorization: OAuth <USER_ACCESS_TOKEN>"

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

API limits

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.

anchor to throttlingThrottling

The Marketing API has a limit of 10 simultaneous connections. You’ll receive an error message if you reach the limit. We do not throttle based on volume. 

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.

anchor to stream-timeoutsStream 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 the pagination and partial response capabilities to request only what is essential to you. 

Note: If you’re regularly seeing issues with timeouts and are unable to optimize your requests using pagination, you might consider sending long-running requests to the Batch endpoint.