Export Data Using the API

The Mailchimp Export API endpoint allows you to access large sets of data that would otherwise be difficult or slow to retrieve. The Export API allows you to get list/audience information and contact activity quickly, but it does not support filtering, sorting, or paging the results like API 3.0.

Submit URL and Parameters

The Export API endpoint is datacenter-specific, just like the API 3.0 endpoints.

The generic format for the API endpoint 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.

Authentication and Request Parameters

Unlike API 3.0, 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.

Request data is passed to the API by POSTing JSON objects to the API endpoints with the appropriate parameters.

Output Formats

Currently JSON is the only output format supported. This means that a call to this API will not return a single valid JSON object but, rather a series of valid JSON objects separated by newline characters.

While this may seem counter-intuitive at first, 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 generating a similarly large JSON object to work with, each item can be operated on immediately. This allows your application to perform the desired actions on the item and then discard the data, keeping the memory footprint of your application low.

HTTPS / Secure Connections

Mailchimp gives a valid, signed certificate for all API methods. If you are manually coding submit URLs, change http to https in the URL, and make sure your connection library supports HTTPS.

List/Audience Export

Exports contacts in a list/audience and all of the associated details. This is a similar to exporting via the web interface.

Full URL:

https://<dc>.api.mailchimp.com/export/1.0/list/

Request Parameters:

Parameter Description
apikey A valid API Key for your Mailchimp account.
id The list id to get contacts from.
status (Optional) The status of the contact contact (subscribed, unsubscribed, cleaned) in the list/audience - defaults to subscribed.
segment (Optional) Pulls only a certain segment of your list/audience.
since (Optional) Only returns contacts whose data has changed since a GMT timestamp – in YYYY-MM-DD HH:mm:ss format
hashed (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 “sha256” is supported.
include_tags (Optional) - Whether to include tags in the response (true or false). The default without this parameter is false, tags are not returned.

Returns:

Parameter Description
text A plain text dump of JSON objects. The first row is a header row. Each additional row is an individual JSON object. Rows are delimited using a newline (\n) marker, so implementations can read in a single line at a time, handle it, and move on.

Subscriber Activity Export

Exports all subscriber activity for a campaign.

Full URL:

https://<dc>.api.mailchimp.com/export/1.0/campaignSubscriberActivity/

Request Parameters:

Parameter Description
apikey A valid API Key for your Mailchimp account.
id The campaign ID to get contact activity from.
include_empty (Optional) If set to “true”, a record for every contact sent to will be returned even if there is no activity data. Defaults to “false”.
since (Optional) Only returns activity recorded since a GMT timestamp – in YYYY-MM-DD HH:mm:ss format.

Returns:

Parameter Description
text A plain text dump of JSON objects. The first row is a header row. Each additional row returned is an individual JSON object. Rows are delimited using a newline (\n) marker, so implementations can read in a single line at a time, handle it, and move on.