Get Started with the MailChimp API 3.0
With MailChimp API 3.0, you can sync email activity and campaign stats with your database, manage lists, create and edit Automation workflows, and test different calls and endpoints before pushing to production.
After reading through this guide, be sure to check out the API Reference to see all available API requests, and visit the Playground to test calls in real-time with your own data.
Before You Start
The MailChimp API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with RESTful APIs. If you think you may need some help integrating with the MailChimp API, visit the Plugins and Integrations Directory to see if someone has already created a tool that meets your needs or connect with one of our experts to help develop a custom tool for you.
The REST architectural style is an integral part of API 3.0. If you’d like to learn more about REST before using the API, check out the Introduction to REST guide.
Resources
Resources are typically nouns like ‘subscribers’ or ‘campaigns’ that you take actions on using supported HTTP verbs. 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 last part of your MailChimp API key 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’re looking for information about lists, 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}.
Authentication
There are 2 authentication methods for the API: HTTP Basic authentication and OAuth2. The easiest way to authenticate is using HTTP Basic authentication. Enter any string as your username and supply your API Key as the password. Your HTTP client library should have built-in support for Basic authentication, but here’s a quick example that shows how to authenticate with the --user option in curl:
curl --request GET \
--url 'https://<dc>.api.mailchimp.com/3.0/' \
--user 'anystring:<your_apikey>'
HTTP Methods
The MailChimp API supports 5 HTTP methods for interacting with resources:
- GETMake a GET request to retrieve data. GET requests will never cause an update or change to your data because they’re safe and idempotent.
- POSTUse 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. - PATCHMake a PATCH request to update a resource. With PATCH requests, you only need to provide the data you want to change.
- PUTUse a PUT request to create or update a resource. This is most useful for syncing subscriber data.
- DELETEMake a DELETE request to remove a resource.
Note
If your ISP doesn’t permit HTTP operations other than GET or POST, use HTTP Method tunneling: make your call with POST, but include the method you intend to use in an X-HTTP-Method-Override header.
Actions
In some places in the MailChimp API, we need to deviate from traditional REST guidelines. Completely removing verbs isn’t possible for every type of request, like pausing an Automation workflow. To pause an Automation workflow, you make a POST request to /automations/{workflow_id}/emails/{id}/actions/pause, but all action endpoints are namespaced this way.
When we talk about supported methods in the API Reference, we refer to these endpoints differently. Any endpoint that uses actions is prefixed with an ACTIONlabel instead of a CREATE label, and appears under the Actions tab instead of the Create tab.
SSL
We give a valid, signed certificate for all API methods. If you’re manually coding submit URLs, change http to https in the URL, and make sure your connection library supports HTTPS.
JSON
The MailChimp API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PATCH requests require a valid JSON object for the body. The API Reference includes complete examples, but here’s a quick look at the JSON format we’re looking for in POST and PATCH requests:
{
"name": "Freddie's Favorite Hats",
"contact": {
"company": "MailChimp",
"address1": "675 Ponce De Leon Ave NE",
"address2": "Suite 5000",
"city": "Atlanta",
"state": "GA",
"zip": "30308",
"country": "US",
"phone": ""
},
"permission_reminder": "You're receiving this email because you signed up for updates about Freddie's newest hats.",
"campaign_defaults": {
"from_name": "Freddie",
"from_email": "freddie@freddiehats.com",
"subject": "",
"language": "en"
},
"email_type_option": true
}
Parameters
There are 4 main categories of parameters for each endpoint in the MailChimp API: path, query string, request body, and response body. The API Reference includes a list of all available parameters for each possible request, but these sections offer an overview of the 4 main categories and their subcategories.
Path parameters
In an API URL, we include resource names and unique identifiers to 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}
In that URL, there is 1 primary resource, lists, and 2 subresources: members, and notes. There are also 3 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 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?option1=foo&option2=bar
Filtering
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 RSS campaigns, use /3.0/campaigns?type=rss
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. We use offset and countin the URL query string to paginate because it provides greater control over how you view your data.
Offset defaults to 0, so if you use offset=1, you’ll miss the first element in the dataset. Count defaults to 10. For example, this URL includes query string parameters for pagination:
https://usX.api.mailchimp.com/3.0/campaigns?offset=0&count=10
Partial responses
Use field parameters to cut down on data transfers by limiting which fields the MailChimp 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 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 shows you all the available request parameters for each endpoint, including required fields. The following example shows you how to create a new list with an HTTP POST request using curl (note the format of the --data option).
curl --request POST \
--url 'https://usX.api.mailchimp.com/3.0/lists' \
--user 'anystring:apikey' \
--header 'content-type: application/json' \
--data '{"name":"Freddie'\''s Favorite Hats","contact":{"company":"MailChimp","address1":"675 Ponce De Leon Ave NE","address2":"Suite 5000","city":"Atlanta","state":"GA","zip":"30308","country":"US","phone":""},"permission_reminder":"You'\''re receiving this email because you signed up for updates about Freddie'\''s newest hats.","campaign_defaults":{"from_name":"Freddie","from_email":"freddie@freddiehats.com","subject":"","language":"en"},"email_type_option":true}' \
--include
Response body parameters
Every API call response includes headers and an optional JSON-formatted body.
Note
DELETE requests return only headers without a JSON body.
The API Reference includes all possible response body parameters, but the following example shows the type of JSON-formatted response to expect from a POST request to the /lists endpoint:
{
"id": "1510500e0b",
"name": "Freddie’s Favorite Hats",
"contact": {
"company": "MailChimp",
"address1": "675 Ponce De Leon Ave NE",
"address2": "Suite 5000",
"city": "Atlanta",
"state": "GA",
"zip": "30308",
"country": "US",
"phone": ""
},
"permission_reminder": "",
"use_archive_bar": true,
"campaign_defaults": {
"from_name": "Freddie",
"from_email": "freddie@freddiehats.com",
"subject": "",
"language": "en"
},
"notify_on_subscribe": "",
"notify_on_unsubscribe": "",
"date_created": "2015-09-16T14:55:51+00:00",
"list_rating": 0,
"email_type_option": true,
"subscribe_url_short": "http://eepurl.com/xxxx",
"subscribe_url_long": "http://freddieshats.usX.list-manage.com/subscribe?u=8d3a3db4d97663a9074efcc16&id=1510500e0b",
"beamer_address": "usX-xxxx-xxxx@inbound.mailchimp.com",
"visibility": "pub",
"modules": [],
"stats": {
"member_count": 0,
"unsubscribe_count": 0,
"cleaned_count": 0,
"member_count_since_send": 0,
"unsubscribe_count_since_send": 0,
"cleaned_count_since_send": 0,
"campaign_count": 0,
"campaign_last_sent": "",
"merge_field_count": 2,
"avg_sub_rate": 0,
"avg_unsub_rate": 0,
"target_sub_rate": 0,
"open_rate": 0,
"click_rate": 0,
"last_sub_date": "",
"last_unsub_date": ""
},
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Instance.json"
},
{
"rel": "parent",
"href": "https://usX.api.mailchimp.com/3.0/lists",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists.json"
},
{
"rel": "update",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b",
"method": "PATCH",
"schema": "https://api.mailchimp.com/schema/3.0/Lists/Instance.json"
},
{
"rel": "delete",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b",
"method": "DELETE"
},
{
"rel": "abuse-reports",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/abuse-reports",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Abuse/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Abuse.json"
},
{
"rel": "activity",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/activity",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Activity/Collection.json"
},
{
"rel": "clients",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/clients",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Clients/Collection.json"
},
{
"rel": "growth-history",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/growth-history",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Growth/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Growth.json"
},
{
"rel": "interest-categories",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/interest-categories",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/InterestCategories/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/InterestCategories.json"
},
{
"rel": "members",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/members",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Members/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Members.json"
},
{
"rel": "merge-fields",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/merge-fields",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/MergeFields/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/MergeFields.json"
},
{
"rel": "segments",
"href": "https://usX.api.mailchimp.com/3.0/lists/1510500e0b/segments",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Segments/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists/Segments.json"
}
]
}
Code Examples
Throughout the MailChimp API documentation, we include code examples so you know how to format your requests, and what kind of data to expect in return.
We use curl to show all requests. For example, the following code snippet shows a POST request to the /listsendpoint:
curl --request POST \
--url 'https://usX.api.mailchimp.com/3.0/lists' \
--user 'anystring:apikey' \
--header 'content-type: application/json' \
--data '{"name":"Freddie'\''s Favorite Hats","contact":{"company":"MailChimp","address1":"675 Ponce De Leon Ave NE","address2":"Suite 5000","city":"Atlanta","state":"GA","zip":"30308","country":"US","phone":""},"permission_reminder":"You'\''re receiving this email because you signed up for updates about Freddie'\''s newest hats.","campaign_defaults":{"from_name":"Freddie","from_email":"freddie@freddiehats.com","subject":"","language":"en"},"email_type_option":true}' \
--include
For most example requests, we use the same set of curl commands:
- requestThe type of HTTP request to make, one of POST, GET, PATCH, DELETE, or PUT.
- urlThe API URL to request.
- userSets the username and password for authenticating with API 3.0. Use any string as the username (before the colon), but you must include your MailChimp API key as the password (after the colon).
- dataThe JSON-formatted request body. Required for most POST, PATCH, and PUT requests.
- includeWhether to show HTTP headers in the response. Use this option if you’re just getting started with the API or troubleshooting, as we return error information in both the HTTP headers (as an HTTP status code) and body.
We use the long, double-dash form for curl options for readability, but you’re welcome to use the short, single-dash form if you prefer.
To show example responses, we include a JSON object in pretty-print format. For example, here’s a response to a GET request to the root endpoint for API 3.0:
{
"account_id": "8d3a3db4d97663a9074efcc16",
"account_name": "Freddie’s Jokes",
"contact": {
"company": "Freddie’s Jokes",
"addr1": "675 Ponce De Leon Ave NE",
"addr2": "Suite 5000",
"city": "Atlanta",
"state": "GA",
"zip": "30308",
"country": "US"
},
"last_login": "2015-09-15 14:25:37",
"total_subscribers": 413,
"_links": [
{
"rel": "self",
"href": "https://usX.api.mailchimp.com/3.0/",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Root.json"
},
{
"rel": "lists",
"href": "https://usX.api.mailchimp.com/3.0/lists",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Lists/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Lists.json"
},
{
"rel": "reports",
"href": "https://usX.api.mailchimp.com/3.0/reports",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Reports/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Reports.json"
},
{
"rel": "conversations",
"href": "https://usX.api.mailchimp.com/3.0/conversations",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Conversations/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Conversations.json"
},
{
"rel": "campaigns",
"href": "https://usX.api.mailchimp.com/3.0/campaigns",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Campaigns/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Campaigns.json"
},
{
"rel": "automations",
"href": "https://usX.api.mailchimp.com/3.0/automations",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Automations/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Automations.json"
},
{
"rel": "templates",
"href": "https://usX.api.mailchimp.com/3.0/templates",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/Templates/Collection.json",
"schema": "https://api.mailchimp.com/schema/3.0/CollectionLinks/Templates.json"
},
{
"rel": "file-manager",
"href": "https://usX.api.mailchimp.com/3.0/file-manager",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/FileManager/Namespace.json"
},
{
"rel": "authorized-apps",
"href": "https://usX.api.mailchimp.com/3.0/authorized-apps",
"method": "GET",
"targetSchema": "https://api.mailchimp.com/schema/3.0/AuthorizedApps/Collection.json"
}
]
}
JSON Schema
We expose publicly-available JSON schema documents for the MailChimp API. Use the schema files to generate documentation, wrapper libraries, or just browse them manually by visiting https://api.mailchimp.com/schema/3.0/Root.json or the Playground.
The following list describes each of the relevant parts of a schema file.
- The
schemaproperty links to the schema that describes the data you should send. - The
targetSchemaproperty describes what comes back on a successful request. - For GET links, the schema describes how to build a query string.
- For POST, PATCH, and PUT links, the schemas describe the JSON object you should send.
- Schema files also include a
_linkssection that can help you navigate from one resource to another and show available actions.
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:
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:
{"type":"http://kb.mailchimp.com/api/error-docs/405-method-not-allowed","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, we recommend reviewing the error glossary for 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 @MailChimpStatusand @MailChimp_API on Twitter to see if we’re experiencing any system-wide issues.
Otherwise, you’re welcome to contact our support team. If you contact support, we recommend including the complete request you’re trying to make and the error code and response you’re receiving so they can help as quickly as possible.
Test error handling
To test error handling, trigger errors yourself by sending an X-Trigger-Errorheader 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.
Throttling
To improve connections and experiences for all our users, we use some connection limits when we see suspicious activity or other overload. Each user account is permitted up to 10 simultaneous connections, and you’ll receive an error message if you reach the limit. We don’t throttle based on volume.
Timeouts
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.
Most core network libraries have a default timeout of 30 seconds. Our wrappers default to 300 seconds (five minutes). If you’re sending short calls, you shouldn’t notice an issue. Sometimes even a short call can experience a timeout if the server is under a heavy load.
A stream timeout doesn’t return any response or error. If your library supports a timeout value, this is likely the culprit, and we recommend testing and editing this value as needed. Here are some more tips to help you troubleshoot stream timeouts:
- Look at how long the calls you’re making typically take and double or triple the timeout value.
- Run short and long calls. Get to know your library, and set timeouts differently based on what your code is doing.
- Queue your calls to run in the background, instead of running them inline to reduce time and load.
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’s a problem right away. High network latency, high server load, saturation, or blockages on your remote server can lead to connectivity timeouts.
You’re welcome to edit timeout values as needed in your own wrappers, but we typically recommend keeping the values low. For example, you might set the connection timeout as high as 60 seconds, but even that may be higher than necessary in most normal scenarios.
Downtime
MailChimp’s API has a 99.9% uptime. We’re rarely offline for planned maintenance, for example as part of major releases. If we do have downtime, we’ll tweet information from @MailChimp or @Mailchimp_API. We may also add a blog post or an in-app message, visible when you log in to your account.
Support
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 likely means there’s an error on MailChimp’s side, and you can check our Twitter accounts, @Mailchimp_APIand @MailChimpStatus 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 for help from the engineering community or others familiar with the MailChimp API.
Roadmap
We’re always working to improve the MailChimp API. Check out the list of planned additions and enhancements for future releases, and sign up to receive MailChimp API announcements. This list is in alphabetical order, and we may add or remove items from the list as needed.
If one of these features is critical to your integration, please let us know.
- Campaign creation and editing
- E-commerce
- User management
- Wrapper libraries
Comments
Post a Comment