Account Exports
The basics
You can download your Mailchimp account’s data with a single request, via either the Mailchimp app or the Marketing API. The exported data—which will be provided as a .zip file—can include audiences, campaign content, template content, gallery assets, contact events, and both aggregate and granular reporting data for sent campaigns.
After an export is requested, it will build in the background for anywhere from a few minutes to (in rare cases) a few days. The eventual .zip can then be downloaded for up to 90 days.
In this doc we’ll explain how to make a request via the Account Exports endpoint, including the options for choosing which data should be included. We’ll also run through the limitations of the export functionality, and the error messages you may encounter if something goes wrong.
If you’d prefer to export via the Mailchimp app, follow the steps detailed here. (Note that only account Managers, Admins, or Owners can export via the app.
While this doc also covers the legacy Export API, this API will only be supported until June 1, 2023. After that date, users will need to switch to the new Account Exports endpoint. This endpoint is better supported and offers superior performance, such as the ability to check on the status of exports during generation.
Generate a new export
When requesting a new export via the Account Exports endpoint, you’ll need:
The category of data (the stage) you want included in the export
Requests to the Account Exports endpoint should be structured like so:
Make a request to the Account Exports endpoint
curl -X POST \
https://${dc}.api.mailchimp.com/3.0/account-exports \
--user "anystring:${apikey}"' \
-d '{"include_stages":["audiences", "gallery_files"]}'
This example would generate an export containing all of a user’s contact data, as well as any image and content assets in their gallery.
API parameters
The include_stages
parameter tells the API which categories of information you’d like in your final download. Each request must include at least one stage, but you can request as many as you’d like.
These stages are:
Stage | Description |
---|---|
| A folder with separate files for cleaned, subscribed, transactional (non-subscribed), and unsubscribed contacts. |
| A CSV of all regular email campaigns located on the Campaigns page. This includes a |
| A CSV of custom events passed into Mailchimp via the API. Includes timestamps, the event name, and the email address of the contact who created the event. |
| A folder with all image and content assets stored in the My Files section of the content studio in your account. If you have a lot of assets stored in Mailchimp, this file will be large. |
| Different reporting data, split into three folders:
|
| A folder with HTML files of all your email templates. |
Time-limiting an export
If you’d like to limit your export to a specific date and time window, include the optional since_timestamp
parameter. Passing an ISO8601 timestamp will limit the exported data to content generated after that specific time and date.
Say you wanted to pull all of an account’s contact data and content assets that were added after April 4, 2000, at midnight UTC. Your code might look like:
Time-limiting an account export
curl -X POST \
https://${dc}.api.mailchimp.com/3.0/account-exports \
--user "anystring:${apikey}"' \
-d '{"include_stages":["audiences", "gallery_files"], "since_timestamp": 2000-04-04T00:00:01+00:00}'
Downloading the data
To see and download all previous exports that have completed within the last 90 days, make a GET request to the Account Exports endpoint. This will allow you to iterate through and download any previously completed exports using the download_url
property in each item of the response. Each download_url
links out to a file hosted by Google, our storage provider.
Each file URL is signed, and only accessible through the given URL. Please keep this URL as private as your API key: it provides direct and unauthorized user access to your account's data without any kind of user verification.
Limits on exports
The same export limits apply for both the Mailchimp app and the API: you can only generate one export at a time, and only one export can be generated per 24-hour period.
Via the API, when these limits come into play you’ll get a 400
exception status code, accompanied by one of the following error messages:
Account Export in Progress: Another export is already in progress. Wait until it’s done before trying to begin another one.
Too Many Account Exports: The last export attempt was less than 24 hours ago. Each export’s
finished
field will be timestamped at completion, and 24 hours after that point another export may be requested.
Legacy Export API
The single-purpose Export API provides support for some of Mailchimp’s account export functionality, such as retrieving list/audience or contact activity information, or keeping campaign subscriber or audience data synced to your external platform. (Note that the Export API does not support result filtering, sorting, or pagination.)
Note: The Export API will no longer be supported after June 1, 2023. After this date, you'll need to make use of the Account Exports endpoint in the Marketing API instead.
API Parameters
The root directory of the Export API is:
https://<dc>.api.mailchimp.com/export/1.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/export/1.0/
.
Unlike the Marketing API, the Export API does not use HTTP basic authentication. Instead, you’ll authenticate requests by providing your account’s API key as the value for the apikey
parameter.
To make a request, POST the request parameters (documented below) as form data or a JSON object. When using form data, be sure to include the trailing slash in the URL before appending your query parameters.
Output formats
JSON is the only supported output format. A call to the Export API will not return a single valid JSON object, but instead a series of valid JSON objects separated by newline characters.
This may seem counterintuitive at first, but the format is better suited to large datasets than a single JSON object would be. Rather than receiving and processing the entire response (which could be many megabytes of data) and working with a similarly large JSON object, you can operate on each item immediately. This allows your application to perform the desired actions on each item and then discard the data, keeping the memory footprint of your application low.
Note: To receive and process export data in a more traditional fashion, take a look at the Batch endpoint.
Errors
The Export API returns errors as an error message and code. The code is a custom Mailchimp status code, and does not correspond to an HTTP status code. Export API errors will still return an HTTP status code of 200
, except in the case of unexpected backend failures, which will return HTTP 500
.
List/audience export
Similar to exporting via the Mailchimp app, the list/audience export will give you contacts in a list/audience and all of their associated details. This endpoint is only available when authenticated at the Admin or Owner user level.
The full URL is https://<dc>.api.mailchimp.com/export/1.0/list/
and the request parameters are as follows:
Parameter | Description |
---|---|
| A valid API key for your Mailchimp account. |
| The list ID to get contacts from. |
| Optional: Filters by contact status ( |
| Optional: Pulls only a certain segment of your list/audience. |
| Optional: Only returns contacts whose data has changed since a UTC timestamp, in YYYY-MM-DD HH:mm:ss format. |
| Optional: If, instead of full list/audience data, you’d prefer a hashed list of email addresses, set this to the hashing algorithm you expect. Currently, only |
| Optional: Whether to include tags in the response ( |
This export will return a plain-text dump of JSON objects, with the
first row as a header row and each additional row as an individual JSON
object. Rows are delimited using a newline (\n
), so implementations can read in a single line at a time, handle it, and move on:
List/audience export sample output
["Email Address","First Name","Last
Name","Birthday","MEMBER_RATING","OPTIN_TIME","OPTIN_IP","CONFIRM_TIME","CONFIRM_IP","LATITUDE","LONGITUDE","GMTOFF","DSTOFF","TIMEZONE","CC","REGION","LAST_CHANGED","LEID","EUID","NOTES"]
["gladys.mcvankab@example.com","Gladys","McVankab","",4,"2018-03-15 17:51:42",null,"2018-03-15
17:51:42","205.201.132.5",null,null,null,null,null,null,null,"2018-03-15 17:51:42",67042739,"77514fa407",null]
["cat@example.com","Kitty","Cat","",2,"2021-02-23 15:22:16",null,"2021-02-23
15:22:16","205.201.132.5",null,null,null,null,null,null,null,"2021-02-23 15:22:16",171106435,"52e230f061",null]
Subscriber activity export
The subscriber activity export gives you all subscriber activity for a campaign. This endpoint is only available for Manager and higher access levels.
The full URL is https://<dc>.api.mailchimp.com/export/1.0/campaignSubscriberActivity/
and the request parameters are as follows:
Parameter | Description |
---|---|
| A valid API key for your Mailchimp account. |
| The campaign ID to get contact activity from. |
| Optional: If set to |
| Optional: Only returns activity recorded since a UTC timestamp, in YYYY-MM-DD HH:mm:ss format. |
Like the list/audience export, the subscriber activity export will return a plain-text dump of JSON objects, with each row as an individual JSON object. Rows are delimited using a newline (\n
).
Subscriber activity export sample output
{"gladys.mcvankab@example.com":[{"action":"open","timestamp":"2017-02-04
09:03:37","url":null,"ip":"66.249.88.40"},{"action":"open","timestamp":"2017-02-04
13:22:40","url":null,"ip":"66.249.88.49"}]}
{"cat@example.com":[{"action":"open","timestamp":"2017-02-05 02:01:33","url":null,"ip":"64.233.172.140"}]}