Methods and Parameters

The Mailchimp Marketing API largely follows RESTful API conventions, providing resources and actions at specified URIs. This documentation covers the structure of these URIs and how to place calls to them, as well as how to design your calls to be as efficient as possible. For further details on the requirements of any particular endpoint, consult the full API reference.

The Mailchimp Marketing API accepts the standard HTTP methods: GET, POST, PATCH, PUT, and DELETE.

• 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 where the body of your request JSON contains all of the required information about the new object to be added to the collection.

• 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.

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.

If your firewall rules do not support HTTP methods like PATCH or DELETE, use the X-HTTP-Method-Override header. Make your call using the POST method and pass the unsupported method as the value of X-HTTP-Method-Override. The override will not work with any method other than POST; if you use the override header with GET, PATCH, PUT, or DELETE, you will receive an error.

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. DELETE requests always return only headers without a JSON body; this could cause issues if your JSON parser does not handle empty responses well. Additionally, the 204 No Content error does not include any JSON body content. The API reference details the specific response for each API call.

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 need to be replaced with real values from your Mailchimp account. Resource identifier placeholders are indicated in curly brackets throughout this documentation.

Resources can be nested several levels deep in a path, such as https://<dc>.api.mailchimp.com/3.0/lists/{list_id}/members/{subscriber_hash}/notes/{id}. In this example, 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://us6.api.mailchimp.com/3.0/lists/57afe96172/members/62eeb292278cc15f5817cb78f7790b08/notes

When making a call for information about a particular contact, the Marketing API uses the MD5 hash of the lowercase version of the contact’s email address. We use 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 users’ email addresses remain unexposed. 

You also 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. Simply calculating the MD5 hash of the lowercase version of your user’s email address allows you to use the email address as a canonical identifier that’s shared across your data model and Mailchimp’s. 

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 optional parameters:

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

Filtering resources

There are two ways to limit the size and complexity of the responses to your API calls: pagination and partial responses. The API reference shows you which resources you can filter on, and what to include in your URL query string. If you provide multiple filters, the Marketing API only returns resources that match all filters.

Pagination

You can 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.

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 or exclude_fields parameter to cut down on response size by limiting which fields the Marketing API returns. 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 or exclude. 

If your calls are failing to return the correct fields, make sure that your request exactly matches the structure of the response JSON, which is determined by the particular endpoint you are accessing. Any nested fields are referenced by dot notation.

For example, the following URL uses the fields query string parameter to only include the audience name (lists.name) and ID (lists.id) fields in the response:

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

However, if you wanted to return just the name of a specific audience, you would do so with the /lists/{list_id} endpoint and the audience name field should be referred to as name, like this:

https://usX.api.mailchimp.com/3.0/lists/{list_id}?fields=name 

This is because response for this endpoint returns a differently structured JSON object—name is at the top level, not embedded in another object named lists.