Methods and Parameters
The basics
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.
HTTP methods
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.
Note: You won’t need to worry too much about these implementation details if you’re using the official client libraries.
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.
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 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
Note: We refer to some endpoints by name and others by URI. For example, you can find a collection of reports at the Reports endpoint, or individual reports at the /reports/{campaign_id} endpoint.
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.
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 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.
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
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
.
Note: The fields
and exclude_fields
parameters are mutually exclusive and will throw an error if a field isn’t valid in your request.