Mailchimp is one of the more popular online marketing tools, best knowing for helping businesses manage their email campaigns but who have a broad set of services.
Just want to sync mailchimp data?
If you don’t want to call the API directly and write glue code, JMES paths and just want the data sync’d to your data platform of choice? SyncWith does this for 100,000s of users and businesses:
- Syncing mailchimp
to
Google Sheets
- install our Google Sheets addon used by 100,000s of other data users
- Sync mailchimp API
to
Airtable
- contact support to join our beta
- Connect mailchimp Data
to
Excel
- install our Excel addon or contact support
- Export mailchimp Data
to
Data Studio
- contact support to join our beta
- Mailchimp API
to
Databases
(S3, BigQuery, MySQL, Postgres, Azure) - contact support to join our beta
Related MailChimp Tutorials and content
Learn how to use SyncWith to access your Mailchimp campaign open report.
In this tutorial we'll show how to track your Mailchimp campaign metrics including open rate, click through rate and more
Call the MailChimp API Directly
Mailchimp API Key
Your Account
If you’re calling the API for your account you’ll use an API key. You an get one from the API Keys section of your Mailchimp account. You can setup multiple keys with different names - typically you’d have one key per application so you can easily revoke access.
Access Mailchimp on behalf of Others
If you’re access Mailchip on behalf of users you’ll need to setup authentication via Oauth 2. Oath uses auth0s work flow which will deliver your application a non expiring token via Mailchimp’s OAuth page.
Mailchimp will require you to register your application:
- Navigate to the Registered Apps page in your Mailchimp account
- Click Register An App
- Set up your server to
- Redirect the user to
https://login.mailchimp.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
- Use the
code
query string parameter passed back to request a access token athttps://login.mailchimp.com/oauth2/token
- https://mailchimp.com/developer/marketing/guides/access-user-data-oauth-2/ has a detail breakdown of how to setup OAuth2 including a code sample
Server Code
When calling the api you also need to specify your server prefix, this can be round by logging into Mailchip and looking at the prefix to mailchimp.com, for example:
- https://
us7
.admin.mailchimp.com/
- server prefix is
us7
Warning
Your MailChimp API key provides full account access - so be sure to protect it and keep it secure.
Client Libraries
Mailchimp provides a set of helpful client libraries for interacting with the API. Your options are:
BASH
No library, just use curl, eg:
# install jq: https://stedolan.github.io/jq/download/ dc="YOUR_DC" apikey="YOUR_API_KEY" curl -sS \ "https://${dc}.api.mailchimp.com/3.0/ping" \ --user "anystring:${apikey}" | jq -r
NODE.JS
yarn add @mailchimp/mailchimp_marketing # OR npm install @mailchimp/mailchimp_marketing
eg
const mailchimp = require("@mailchimp/mailchimp_marketing"); mailchimp.setConfig({ apiKey: "YOUR_API_KEY", server: "YOUR_SERVER_PREFIX", }); async function run() { const response = await mailchimp.ping.get(); console.log(response); } run();
PHP
composer require mailchimp/marketing
eg
require_once('/path/to/MailchimpMarketing/vendor/autoload.php'); $mailchimp = new \MailchimpMarketing\ApiClient(); $mailchimp->setConfig([ 'apiKey' => 'YOUR_API_KEY', 'server' => 'YOUR_SERVER_PREFIX' ]); $response = $mailchimp->ping->get(); print_r($response);
PYTHON
pip install mailchimp-marketing
eg
from mailchimp_marketing import Client mailchimp = Client() mailchimp.set_config({ "api_key": "YOUR_API_KEY", "server": "YOUR_SERVER_PREFIX" }) response = mailchimp.ping.get() print(response)
RUBY
gem install MailchimpMarketing
eg
require "MailchimpMarketing" mailchimp = MailchimpMarketing::Client.new mailchimp.set_config({ :api_key => ENV["API_KEY"], :server => ENV["API_SERVER"] }) response = mailchimp.ping.get puts response
Response
The API provides a response back in JSON, in the above examples the ping endpoint was called:
https://{server}.api.mailchimp.com/3.0/ping
which sends back a simple JSON response:{ "health_status": "Everything's Chimpy!" }
API Limits
- 10 simultaneous connections with a 429 error if you hit the limit.
- 120-second timeout on API calls. Typical if you’ve made a network socket connection and are already sending and receiving data.
- Some responses are slow to calculate and if you are requesting too much you can bump into the timeout limit. Use pagination and partial responses to avoid timeouts.
Versions
- Currently on version 3.0, 1.0 no longer works and 2.0 live but deprecated and unsupported
- Version can be see in the endpoint URL - https://{server}.api.mailchimp.com/
3.0
/{endpoint}
Structure
- Endpoints largely let you get / modify resources such as subscriber and campaigns
- Actions are representted by standard HTTP REST API methods
GET
- to pull existing recordsPOST
- to create new recordsPUT
- to edit existing recordsDELETE
- to delete records
Common Query Parameters
count
- used to set the maximum number of records returned, default is 10, max is 1000
offset
- used for pagination in order to skip the first x records, defaults to 0
Common Success Response
total_items
- limits the total number of items that match the request regardless of pagination
Popular Endpoints
The root URL for all the endpoints is https://{server}.api.mailchimp.com/3.0/
{endpoint}
where {endpoint}
is replaced with the specific endpoint you’re looking to use - campaigns
For a complete listing of templates mailchimp provides detailed documentation: https://mailchimp.com/developer/marketing/api/root/
GET /3.0/reports
- Reports on campaigns
https://{server}.api.mailchimp.com/3.0/reports
- Additional query params
before_send_time
- campaigns sent before the set time, uses ISO 8601 -YYYY-MM-DDTHH:MM:SS+00:00
since_send_time
- campaigns sent after the set timetype
sets the campaign type:regular
,plaintext
,absplit
,rss
,variate
GET /3.0/lists/{list_id}/members
- Get members of a specific Mailchimp list
- Includes subscribed, unsubscribed and bounced members
- Reguires the
{list_id}
for the list you want the members of
- Additional query params
fields
- csv of fields to returnexclude_fields
- csv of fields not to returnstatus
- status of the member, possible values include:- subscribed
- unsubscribed
- cleaned
- pending
- transactional
- archived
- Date filters specified in ISO 8601 (
YYYY-MM-DDTHH:MM:SS+00:00
) including: since_timestamp_opt
- opted in after a set timebefore_timestamp_opt
- opted in before a set timesince_last_changed
- subscribers whose information has changed since a set time)before_last_changed
- subscribers whose information changed before a set timeunsubscribed_since
- only unsubscribers who unsubscribed since a speccific datevip_only
- boolean (true
orfalse
) that returns only VIP membersinterest_ids
- filter by a csv of interest IDs requiresinterest_match
query paraminterest_match
- specifies the type of interest match valid values areany
,all
andnone
sort_field
- sets the sort field. Valid values are Possible values aretimestamp_opt
,timestamp_signup
andlast_changed
sort_dir
- determines the sort order - possible values areASC
andDESC
since_last_campaign
- only subscribers whose status changed since the last email