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.

E-Commerce

The E-commerce endpoints allow you to connect an external store to your Mailchimp account, which in turn allows you to access Mailchimp’s e-commerce features — including order notifications, abandoned cart automations, product follow-ups, recommendations, and more.

Stores 

The Stores endpoint is the top-level e-commerce endpoint. Carts, Customers, Orders, and Products all exist inside of the scope of a store. Each store must be tied to a Mailchimp audience (which uses the list endpoint), but a single audience can support multiple stores. 

When creating a new store, the required store ID is a client-defined identifier. After a Store is created and tied to a list/audience, it cannot be connected to a different list/audience.

Customers

Like the store ID, the customer ID is client-defined. If your e-commerce set up assigns a customer ID (e.g., customer_01, customer_02, customer_03, etc.) you can add the customers to Mailchimp without a new ID string. If a customer’s email address is not already associated with an audience, it will be added with the subscription status determined by the opt_in_status parameter.

An opt_in_status of true will result in a subscribed audience member; false will set the status to transactional. Updating the customer’s opt_in_status from false to true will update the member’s subscription status to subscribed, however updating the opt_in_status from true to false will not change the subscription status.

Note: Customers who have opted out of your Mailchimp audience will be added as transactional members. Although the opt_in_status parameter is there, it will not overwrite the status of a pre-existing contact. False = transactional; true = subscribed.

Products

A product represents an item for sale in a store. Each product exists as its own parent entity that must contain one or more product variants and must be added to a store before it can be added to a cart or an order. You must create products before you can create carts and orders.

Orders

The Orders endpoint represents a successful transaction. When adding orders, the processed_at_foreign parameter is not required. However, if the orders are missing a date and time stamp, they will not show up on a contact’s timeline in the application. 

Note: Bringing over historical purchase data and customers depends on how the platform itself stores data and can be done via batch operations. We recommend bringing at least 6 months of purchase/subscriber data over. This data will help target customers and product recommendation suggestions will be more accurate.

Order notifications

Order notifications are triggered by a change in a contact’s order status. After designing and enabling order notifications in your Mailchimp account, you can trigger those emails by adding or updating an e-commerce order with financial_status or fulfillment_status values.

An order’s financial_status can be paid, pending, refunded, or cancelled. Changing the status will trigger the following notifications:

  • paid :  order invoice, notifying the customer that their order is paid in full

  • pending : order confirmation, notifying a customer if their order is unpaid or partially paid

  • refunded : refund confirmation, notifying a customer that their refund has been processed

  • cancelled : cancellation confirmation, notifying a customer that their order has been cancelled

Setting an order’s fulfillment_status to shipped will trigger a shipping confirmation, notifying a customer that their order has been shipped.

Carts

Use the Carts endpoint to temporarily save a customer’s shopping cart prior to a successful purchase in order to create an abandoned cart automation.

Important: For an abandoned cart automation to work properly, you must specify the checkout_url when creating the cart.

Note: Cart data cannot be converted directly into an order — carts only exist in the e-commerce endpoint for the purpose of triggering abandoned cart automations, and are not used to create orders.

Abandoned cart automation is triggered by carts call. To remove a cart, send the delete call/delete cart. Carts will remain on our systems until deleted.

E-commerce tracking and reports

Add tracking parameters to e-commerce orders to track purchases that result from a campaign, product recommendation, and to monitor how much you are selling with Mailchimp. You can also see data from orders with a campaign_id in any Campaign Report.

When you send a campaign with e-commerce tracking enabled, any links in that campaign’s emails will contain additional tracking parameters that can be used with the e-commerce API.

  • mc_eid is a unique Mailchimp ID that identifies the recipient's email address.

  • mc_cid is the Mailchimp ID for the campaign that generated the link.

Use the mc_eid value from the tracking URL to associate orders with a subscribed contact. You can make an API call to the /lists/{list_id}/members endpoint and specify the member with the unique_email_id query param by the unique_email_id value from the mc_eid in the link to find the email address for that recipient, which you can then use to identify the customer for your order.

For example, if your subscriber's link contains the mc_eid=18d3c1adfe tracking parameter, you can find that customer's email address by making a request to the GET /lists/list_id/members?unique_email_id=18d3c1adfe endpoint.

You can add e-commerce orders with mc_cid ID as the value for the campaign_id parameter to indicate that the order resulted from a specific campaign.

Product recommendations

To enable product recommendations for the orders and products you add to Mailchimp, include the following parameters:

  • Products require a valid image_url so your customers can see images of any recommended products.

  • Product Variants require the inventory_quantity parameter. Product Variants will only be recommended if this value is >0, since we do not want to recommend a specific item unless it is available for purchase.

  • Orders require a processed_at_foreign time stamp. This data ensures that your customer's product recommendations are based on up-to-date e-commerce activity.

Note: You can also track any purchases that result from a Mailchimp Product Recommendation. When a customer clicks on a recommended product, that link will include mc_tc=prec in the URL. Use this value for the tracking_code parameter when adding an order to track revenue resulting from product recommendations.

Double opt-in

Mailchimp offers two opt-in settings for audiences. Double opt-in includes an extra confirmation step that verifies each email address. For double opt-in emails to be sent properly, you will need to make a POST request to the Customers endpoint followed by a PATCH request to the list/{list_id}/members/{subscriber_hash} endpoint.

  1. In the body of the POST request to the Customers endpoint, send a value of false for the opt_in_status field. This adds the customer as a transactional contact. Sending a value of true adds them as a subscriber and opts them into marketing emails.

  2. Next, make a call to edit the contact with a status value of pending. This can be done using a PATCH request to the lists/{list_id}/members/{subscriber_hash} endpoint.

Syncing an e-commerce store

When you create or update a store in Mailchimp with the is_syncing parameter set to true, you will temporarily disable these automations from triggering off of any e-commerce data for that store.

Now you can add, edit, or backfill e-commerce information without sending any of these campaigns:

  • Order notifications

  • Abandoned carts

  • First purchases

  • Specific product follow-ups

  • Any product follow-ups

  • Category follow-ups

  • Best customers

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:

Error response 1

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:

Error response 2

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.