Mailchimp Marketing API

Just want to sync mailchimp data?

• 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

Call the MailChimp API Directly

Mailchimp API Key

Your Account

Access Mailchimp on behalf of Others

1. Navigate to the Registered Apps page in your Mailchimp account

2. Click Register An App

3. Set up your server to
1. Redirect the user to https://login.mailchimp.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
2. Use the code query string parameter passed back to request a access token at https://login.mailchimp.com/oauth2/token

4. 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

• https://us7.admin.mailchimp.com/

• server prefix is us7

Warning

Client Libraries

# 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

yarn add @mailchimp/mailchimp_marketing
# OR
npm install @mailchimp/mailchimp_marketing

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();

composer require mailchimp/marketing

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);

pip install mailchimp-marketing

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)

gem install MailchimpMarketing

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

{
  "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 records
• POST - to create new records
• PUT - to edit existing records
• DELETE - 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

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 time
• type 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 return
• exclude_fields - csv of fields not to return
• status - 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 time
• before_timestamp_opt - opted in before a set time
• since_last_changed - subscribers whose information has changed since a set time)
• before_last_changed - subscribers whose information changed before a set time
• unsubscribed_since - only unsubscribers who unsubscribed since a speccific date
• vip_only - boolean (true or false) that returns only VIP members
• interest_ids - filter by a csv of interest IDs requires
• interest_match query param
• interest_match - specifies the type of interest match valid values are any, all and none
• sort_field - sets the sort field. Valid values are Possible values are timestamp_opt, timestamp_signup and last_changed
• sort_dir - determines the sort order - possible values are ASC and DESC
• since_last_campaign - only subscribers whose status changed since the last email