Marketing API Conventions

At a glance

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.

This document details some of the high-level conventions of the Mailchimp Marketing API.

Authentication methods

You can authenticate requests using either your API key or an OAuth access token. Choose the one that works best for the solution you’re building.

Specifically: Use your API Key if you’re writing code that tightly couples your application’s data to your Mailchimp account’s data. If you ever need to access someone else’s Mailchimp account’s data, you should be using 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 directly against the API, you’ll need to know how to do authentication for your chosen method.

Authenticate with an API key

To make an authenticated request to the API using your API key, you’ll use HTTP Basic authentication. Your request would look something like this:

Authenticate with an API key

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

The user:password combination in the HTTP basic auth is somewhat arbitrary — you can use any string as the user name. Your API key is used where you would normally include your password in an HTTP basic auth request: after the colon.

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.

Authenticate with OAuth 2

If you’re using OAuth 2 to authenticate calls to the Marketing API, you’ll need to send an authorization header along with your request. It would look something like this:

Authenticate with OAuth 2

cURL
curl --request GET \
--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.

User roles

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. Moreover, 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.

HTTP methods

Like most APIs, the Mailchimp Marketing API is not fully RESTful — but Mailchimp follows most of the practices and common definitions of the style. For example, the Marketing API has what we call “resources,” which are typically nouns like “subscribers” or “campaigns.” 

You take action on resources using the standard HTTP methods: POST, GET, PATCH, and DELETE. The Mailchimp API supports these HTTP methods for interacting with resources:

  • Make a GET request to retrieve data. GET requests will never cause an update or change to your data because they're safe and idempotent.

  • Use a POST request to create new resources. For example, make a POST request to a collection endpoint (like /lists) where the body of your request JSON is a new list/audience.

  • Make a PATCH request to update a resource. With PATCH requests, you only need to provide the data you want to change.

  • Use a PUT request to create or update a resource. This is most useful for syncing contact data.

  • Make a DELETE request to remove a resource.

Note: You won’t need to worry too much about these implementation details if you’re using the official client libraries.

If your firewall rules do not support HTTP methods, like PATCH or DELETE, use the X-HTTP-Method-Override header. Pass the method you want to use in the X-HTTP-Method-Override header and make your call using the POST method. The override will not work with any other method, so if you try and use the override header with a GET, PATCH, PUT, or DELETE method, you will receive an error.

Additionally, the 204 No Content error does not include any JSON body content. This is most common with DELETE requests, and could cause issues if your JSON parser does not handle empty responses well.

Resources

The root directory for the API includes a map of all available resources and their subresources:

https://<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 is us6, all API endpoints for your account are available at https://us6.api.mailchimp.com/3.0/.

Each resource is typically separated into a resource/{id} format, with subresources following the same pattern.

For example, if you are looking for information about lists/audiences, make a GET request to https://<dc>.api.mailchimp.com/3.0/lists. To access an individual list, make a GET request to https://<dc>.api.mailchimp.com/3.0/lists/{list_id}.

We also refer to endpoints in our documentation; endpoints are URIs (as opposed to URLs) for individual resources. For example, find a collection of reports by requesting the Reports endpoint, or access individual reports at /reports/{campaign_id}.

Deviations from REST

In some places in the Marketing API, we need to deviate from traditional REST guidelines. 

Verbs we use

Some endpoints act on resources outside of a traditional REST approach. To pause an Automation workflow, for example, you make a POST request to /automations/{workflow_id}/emails/{id}/actions/pause. Where we deviate from the verb usage defined by REST, we namespace those verbs under actions in the URI.

Generic MIME types

Some companies use a custom MIME type for their RESTful APIs instead of the generic JSON type (application/json). The Marketing API uses the generic JSON content type because the benefits of customization are more theoretical than practical.

Self-describing representations

We use the OpenAPI Specification (formerly known as Swagger) to describe each endpoint. This document also contains type information to help you error-check your requests.

Explore our spec at https://api.mailchimp.com/schema/3.0/Swagger.json?expand.

Path parameters

In an API URL, resource names and unique identifiers help you figure out how to structure your requests. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your Mailchimp account. 

Let’s look at an example:

https://usX.api.mailchimp.com/3.0/lists/{list_id}/members/{email_id}/notes/{id}

There is one primary resource, lists, and two subresources, members and notes. There are also three different path parameters that you need to replace with real values from your Mailchimp account: list_id, email_id, and id. When you replace those values with actual data, your final URL should look something like this:

https://usX.api.mailchimp.com/3.0/lists/57afe96172/members/62eeb292278cc15f5817cb78f7790b08/notes

Query string parameters

We use optional query string parameters for filtering, pagination, and partial responses in the Mailchimp API. The format for query string parameters is the full resource URL followed by a question mark and the optional parameters:

https://usX.api.mailchimp.com/3.0/campaigns?count=10&offset=10 

Filtering resources

The API Reference shows you which resources you can filter on, and what to include in your URL query string. For example, to view only plain-text campaigns, use /3.0/campaigns?type=plaintext.

If you provide multiple filters, we only return resources that match all filters.

Pagination

Paginate your API requests to limit response results and make them easier to work with by requesting manageable chunks of data. We use offset and count in the URL query string to paginate because it provides greater control over how you view your data.

Note: The Marketing API has a 120 second timeout on API calls. If you’re requesting a particularly large set of data, pagination can help cut down on request times. Alternatively, you might consider sending long-running requests to the Batch endpoint.

The maximum value for count is 1000; the default value is 10. If not included, offset defaults to 0. (To retrieve the first ten results, set count to 10 and offset to 0. To retrieve the following ten results, the offset should be 10 and the count should remain 10.) This URL represents the default query string parameters for pagination:

https://usX.api.mailchimp.com/3.0/campaigns?offset=0&count=10 

Partial responses

Use the fields parameter to cut down on response size by limiting which fields the Marketing API returns. For example, you may not need the full details of a resource, and can instead pass a comma-separated list of specific fields you want to include.

The parameters fields and exclude_fields are mutually exclusive and will throw an error if a field isn't valid in your request. For example, the following URL uses the fields query string parameter to only include the list/audience name and List ID fields in the response:

https://usX.api.mailchimp.com/3.0/lists?fields=lists.name,lists.id

Request body parameters

For PATCH, PUT, and POST requests, you may need to include a request body in JSON format. The API Reference details all the available request parameters for each endpoint, including required fields.

Response body parameters

Every API call response includes headers and an optional JSON-formatted body. Note that DELETE requests return only headers without a JSON body. Refer to the API Reference for the specific response for each API call.

Referencing contacts by MD5 Hash

The Mailchimp Marketing API identifies an audience’s contacts by the MD5 hash of the lowercase version of their email address. This means that you don't need to maintain a mapping from your contact to Mailchimp’s internal contact ID in your application’s data store, or make additional calls to the API to look up that mapping. 

Instead, the MD5 hash of the lowercase version of your user’s email address — which you likely have stored anyway — allows you to use the email address as a canonical identifier that’s shared across your data model and Mailchimp’s. 

Mailchimp uses the MD5 hash because it makes it less likely to leak email addresses — these hashes can’t be translated back to an email address, so if your APIs calls were leaked in some manner, your user’s email address remains unexposed.

Throttling

To improve connections and experiences for all our users, we use some connection limits. Each user account can have up to 10 simultaneous connections; you’ll receive an error message if you reach the limit. We do not throttle based on volume.

 Note: Currently there are no options to raise the limit on a per-customer basis.

Stream timeouts

A stream timeout can occur if the network code handling the connection has a limit on how long it can pass data. You may see this type of timeout after you've made a network socket connection, and are already sending and receiving data.

For most basic usage, you should not notice an issue. However, response times are dependent on the complexity of your request and the general load across Mailchimp.

Note: The Marketing API has a 120 second timeout on API calls. 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.

Connection timeouts

A connection timeout occurs when the network socket connection fails before you send or receive data. Connection timeouts are usually more manageable than stream timeouts because you know there is a problem right away. High network latency, high server load, saturation, or blockages on your remote server can lead to connectivity timeouts.

Note: In order to maintain the overall health of the service, we have safeguards in place, beyond the concurrent-connection limit, to prevent a single user from making too many expensive calls at once. These safeguards can result in API access being disabled for a given user, so be cognizant of the quantity and complexity of your requests.

Downtime

We are rarely offline for planned maintenance. If we do have downtime, we’ll share information on Twitter via @MailchimpStatus

Fault tolerance

When you use any API, keep in mind that errors and exceptions (e.g., server connection problems or outages) are rare, but they happen. To make sure that your integration is as reliable as it can be, you should always watch for errors and exceptions. If an API call returns an error, log the call in as much detail as you can, including what you sent along with the entire error response and headers. If you need to contact support, this information can speed up the help process.

Reduce response time

Some endpoints in the Marketing API return values that are large and slow to calculate. Once you know what data you need, use our partial response capabilities to request only what is essential to you. 

You can use a combination of pagination and the partial response functionality available via query parameters, like count, offset, fields, and exclude_fields.

Cache values

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 — 10 concurrent connections at a time — and will likely provide faster access to that data.

Support options

To start, we recommend reviewing the errors section in this guide, and method-specific errors for the endpoint you’re trying to access. If you’re seeing a 5xx error, that probably means there’s an error on Mailchimp's side. 

You can check @MailchimpStatus on Twitter or contact our support team at apihelp@mailchimp.com

You can also find answers to frequently asked questions on Stack Overflow, or add a new post to ask for help from the engineering community.

Errors

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format. 

For example, the following code snippet shows an HTTP 405 error in the response headers:

Response

JSON
HTTP/1.1 405 Method Not Allowed
Server: nginx
Content-Type: application/problem+json; charset=utf-8
Content-Length: 253
X-Request-Id: a1efb240-f8d8-40fe-a680-c3a5619a42e9
Link: <https://us2.api.mailchimp.com/schema/3.0/ProblemDetailDocument.json>; rel="describedBy"
Date: Thu, 17 Sep 2015 19:02:28 GMT
Connection: keep-alive
Set-Cookie: _AVESTA_ENVIRONMENT=prod; path=/

And this snippet shows the human-readable error as a JSON object:

Response

JSON
{
  "type": "https://developer.mailchimp.com/documentation/mailchimp/guides/error-glossary/#405",
  "title": "Method Not Allowed",
  "status": 405,
  "detail": "The requested method and resource are not compatible. See the Allow header for this resource's available methods.",
  "instance": ""
}

For HTTP response codes, 4xx codes suggest a bad request. If you receive a 4xx response, the error glossary below offers more context to help you troubleshoot. 5xx errors suggest a problem on Mailchimp's end, so if you receive a 5xx error, we recommend checking @MailchimpStatus on Twitter to see if we are experiencing any system-wide issues.

Otherwise, contact our support team. If you contact support, we recommend including the complete request you are trying to make and the error code and response you are receiving so they can help as quickly as possible.

To test error handling, trigger errors yourself by sending an X-Trigger-Error header with the name of the error to trigger. For example, trigger a 401 error by sending a value of APIKeyMissing in the X-Trigger-Error header.

If an error returns HTML instead of JSON, your request may have timed out. Contact our support team, and note the Ref# provided in the error.

Error glossary

If you run into trouble, here's the list of global errors for the Mailchimp Marketing API. Additionally, you can often find more detail about the error in the JSON response body.

400

BadRequest: Your request could not be processed. This is a generic error.

InvalidAction: The action requested was not valid for this resource. This error is returned when you try to access an action that doesn’t exist.

InvalidResource: The resource submitted could not be validated. For field-specific details, see field_warnings or field_errors objects. This error means that the object submitted to a POST or PATCH request failed to validate against JSON schema, and could relate to campaign, interest group, merge field, or any other available object.

JSONParseError: We encountered an unspecified JSON parsing error. This error means that your JSON was formatted incorrectly or was considered invalid or incomplete.

401

APIKeyMissing: Your request did not include an API key. This error suggests that your API key was missing from your request, or that something was formatted or named improperly in your header. To learn more, check out the Marketing API Quick Start

APIKeyInvalid: Your API key may be invalid, or you've attempted to access the wrong data center. Check that your API key was input correctly, and verify which data center to access. To learn more, check out the Authentication section.

403

Forbidden: You are not permitted to access this resource. This is a generic error.

UserDisabled: This account has been disabled. The Mailchimp account is deactivated. Contact our support team if you need more help.

WrongDatacenter: The API key provided is linked to a different data center. This error suggests that you tried to contact the wrong data center. It’s often associated with misconfigured libraries.

404

ResourceNotFound: The requested resource could not be found. This error tells you a specific resource doesn’t exist. It’s possible that the resource has been moved or deleted, or that there’s a typo in your request.

405

MethodNotAllowed: The requested method and resource are not compatible. See the Allow header for this resource's available methods. This error means that the requested resource does not support the HTTP method you used. Find out which methods are allowed for each resource in the API Reference.

414

ResourceNestingTooDeep: The sub-resource requested is nested too deeply. This uncommon error appears if you’ve tried to generate a URL with too many resources, or if you’ve made a request to a malformed URL.

422

InvalidMethodOverride: You can only use the X-HTTP-Method-Override header with the POST method. This error lets you know you’ve tried to override an incompatible method. The Marketing API only permits method override with POST.

RequestedFieldsInvalid: The fields requested from this resource are invalid. This error suggests there is a typo in your field request or some other type of syntax error or problem that invalidates your request.

429

TooManyRequests: You have exceeded the limit of 10 simultaneous connections. When you reach the connection limit, we’ll throttle server response. If any of your requests time out after you've reached the limit, those requests could still be considered open and continue to slow your connection. Contact the Marketing API support team at apihelp@mailchimp.com if you think this is the case.

500

InternalServerError: An unexpected internal error has occurred. Please contact Support for more information. This error lets you know our servers have experienced a problem. Although this is rare, please contact apihelp@mailchimp.com to let us know that you’ve encountered this error.

503

ComplianceRelated: This method has been disabled. You will see this error when your account is under compliance review.