mailchimp（Mailchimp 邮件管理）

Troubleshooting

If requests fail, run zero doctor check-connector --env-name MAILCHIMP_TOKEN or zero doctor check-connector --url https://us1.api.mailchimp.com/3.0/ping --method GET

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 $MAILCHIMP_TOKEN" | jq '{health_status}'

Get Account Details

curl -s "https://${MC_DC}.api.mailchimp.com/3.0/" --header "Authorization: Bearer $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $MAILCHIMP_TOKEN" --header "Content-Type: application/json" -d @/tmp/mailchimp_request.json | jq '{id, name, stats}'

Guidelines

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