mailchimp

---
name: mailchimp
description: Mailchimp API for email marketing. Use when user mentions "Mailchimp",
  "email campaign", "newsletter", or marketing automation.
---

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

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

### Get Account Details

```bash
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)

```bash
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:

```bash
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:

```bash
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`:

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

```bash
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`:

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

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

```bash
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:

```bash
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`:

```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"
  }
}
```

```bash
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:

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

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

```bash
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`:

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

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