SyncWith

Login

Mailchimp Marketing API

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:
  • mailchimp API to Databases (S3, BigQuery, MySQL, Postgres, Azure) - contact support to join our beta

Related MailChimp Tutorials and content

How to use the Mailchimp Campaign Open Report
Learn how to use SyncWith to access your Mailchimp campaign open report.
Read more
Mailchimp campaign metrics into Google Sheets
In this tutorial we'll show how to track your Mailchimp campaign metrics including open rate, click through rate and more
Read 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:
  1. Navigate to the Registered Apps page in your Mailchimp account
  1. Click Register An App
  1. 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
  1. 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 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

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