Mailchimp Marketing API

Manage audiences (lists), campaigns, templates, and subscribers with the Mailchimp Marketing API v3.0.

Official docs: https://mailchimp.com/developer/marketing/api/

When to Use

Manage audiences/lists and subscribers
Create, send, and analyze email campaigns
Manage email templates
View campaign reports and analytics
Manage tags and segments

Prerequisites

Datacenter

Mailchimp API URLs are datacenter-specific: https://<dc>.api.mailchimp.com/3.0. Before making any API calls, determine the datacenter via the metadata endpoint:

MC_DC=$(curl -s "https://login.mailchimp.com/oauth2/metadata" -H "Authorization: OAuth $(printenv MAILCHIMP_TOKEN)" | jq -r '.dc')

Core APIs

Get Account Info (Ping)

Use this to verify authentication:

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/ping" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '{health_status}'

Get Account Details

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '{account_id, account_name, email, total_subscribers}'

List Audiences (Lists)

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/lists?count=10" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '.lists[] | {id, name, stats: {member_count: .stats.member_count, campaign_count: .stats.campaign_count}}'

Docs: https://mailchimp.com/developer/marketing/api/lists/

Get Audience Details

Replace <list-id> with the actual list/audience ID:

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/lists/<list-id>" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '{id, name, stats, date_created}'

List Members of Audience

Replace <list-id> with the actual list ID:

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/lists/<list-id>/members?count=10" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '.members[] | {id, email_address, status, full_name}'

Add Member to Audience

Replace <list-id> with the actual list ID.

Write to /tmp/mailchimp_request.json:

{
  "email_address": "new.subscriber@example.com",
  "status": "subscribed",
  "merge_fields": {
    "FNAME": "Jane",
    "LNAME": "Doe"
  }
}

curl -s -X POST "https://${MC_DC}.api.mailchimp.com/3.0/lists/<list-id>/members" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" --header "Content-Type: application/json" -d @/tmp/mailchimp_request.json | jq '{id, email_address, status, full_name}'

Docs: https://mailchimp.com/developer/marketing/api/list-members/

Update Member

Replace <list-id> and <subscriber-hash> (MD5 hash of lowercase email):

Write to /tmp/mailchimp_request.json:

{
  "merge_fields": {
    "FNAME": "Janet"
  },
  "tags": ["vip"]
}

curl -s -X PATCH "https://${MC_DC}.api.mailchimp.com/3.0/lists/<list-id>/members/<subscriber-hash>" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" --header "Content-Type: application/json" -d @/tmp/mailchimp_request.json | jq '{id, email_address, status, full_name}'

To compute the subscriber hash: echo -n "email@example.com" | md5sum | cut -d' ' -f1

List Campaigns

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/campaigns?count=10&sort_field=send_time&sort_dir=DESC" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '.campaigns[] | {id, type, status, settings: {subject_line: .settings.subject_line, title: .settings.title}, send_time}'

Docs: https://mailchimp.com/developer/marketing/api/campaigns/

Get Campaign Details

Replace <campaign-id> with the actual campaign ID:

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/campaigns/<campaign-id>" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '{id, type, status, settings, recipients, send_time}'

Create Campaign

Write to /tmp/mailchimp_request.json:

{
  "type": "regular",
  "recipients": {
    "list_id": "<list-id>"
  },
  "settings": {
    "subject_line": "Monthly Newsletter",
    "title": "March 2026 Newsletter",
    "from_name": "My Company",
    "reply_to": "hello@example.com"
  }
}

curl -s -X POST "https://${MC_DC}.api.mailchimp.com/3.0/campaigns" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" --header "Content-Type: application/json" -d @/tmp/mailchimp_request.json | jq '{id, type, status, settings: {subject_line: .settings.subject_line, title: .settings.title}}'

Get Campaign Report

Replace <campaign-id> with the actual campaign ID:

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/reports/<campaign-id>" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '{id, campaign_title, subject_line, emails_sent, opens: {opens_total: .opens.opens_total, unique_opens: .opens.unique_opens, open_rate: .opens.open_rate}, clicks: {clicks_total: .clicks.clicks_total, unique_clicks: .clicks.unique_clicks}}'

Docs: https://mailchimp.com/developer/marketing/api/reports/

List Templates

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/templates?count=10" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" | jq '.templates[] | {id, name, type, date_created}'

Search Members

Write to /tmp/mailchimp_query.txt:

jane@example.com

curl -s -G "https://${MC_DC}.api.mailchimp.com/3.0/search-members" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" --data-urlencode "query@/tmp/mailchimp_query.txt" | jq '.exact_matches.members[] | {id, email_address, full_name, status}'

Create Audience

Write to /tmp/mailchimp_request.json:

{
  "name": "My Newsletter",
  "contact": {
    "company": "My Company",
    "address1": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "90210",
    "country": "US"
  },
  "permission_reminder": "You signed up for our newsletter.",
  "campaign_defaults": {
    "from_name": "My Company",
    "from_email": "hello@example.com",
    "subject": "",
    "language": "en"
  },
  "email_type_option": true
}

curl -s -X POST "https://${MC_DC}.api.mailchimp.com/3.0/lists" --header "Authorization: Bearer $(printenv MAILCHIMP_TOKEN)" --header "Content-Type: application/json" -d @/tmp/mailchimp_request.json | jq '{id, name, stats}'

Guidelines

Datacenter routing: Always determine MC_DC first via the metadata endpoint (see Prerequisites)
Subscriber hash: Member endpoints use MD5 hash of lowercase email as the identifier
Status values: subscribed, unsubscribed, cleaned, pending, transactional
Campaign types: regular, plaintext, absplit, rss, variate
Rate limits: 10 concurrent connections; batch operations available for bulk updates
Pagination: Use count and offset query parameters