cli-anything-mailchimp
Identity
An agent-native CLI for the Mailchimp Marketing API v3.0, built on the CLI-Anything framework.
What This CLI Does
- Manage audiences (lists) — create, update, delete lists; add/update/archive members; manage merge fields, segments, tags, and webhooks.
- Run campaigns — create, schedule, send, pause, replicate, and analyse email campaigns.
- Read reports — open rates, click rates, bounce stats, unsubscribes, email activity, geographic data.
- Control automations — create and manage automated email workflows.
- Manage e-commerce — stores, orders, customers, products, carts, and promo codes.
- Use templates, file manager, landing pages, SMS campaigns, surveys, and all other Marketing API resources.
Prerequisites
- Python 3.10+
MAILCHIMP_API_KEY environment variable set to your API key (including datacenter suffix, e.g. abc123-us8)
Installation
# From the CLI-Anything repo (once merged):
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=mailchimp/agent-harness
# During development:
cd mailchimp/agent-harness && pip install -e .
Command Reference
Root
| Command |
Description |
cli-anything-mailchimp ping |
Health check — confirms API connectivity |
cli-anything-mailchimp root list |
Get account info |
cli-anything-mailchimp --json <cmd> |
Output any command as JSON |
cli-anything-mailchimp |
Launch interactive REPL |
Lists (Audiences)
| Command |
Description |
lists list |
List all audiences |
lists get <LIST_ID> |
Get audience info |
lists create --data '<json>' |
Create audience |
lists update <LIST_ID> --data '<json>' |
Update audience |
lists delete <LIST_ID> |
Delete audience |
lists list-lists-id-members <LIST_ID> |
List members |
lists get-lists-id-members-id <LIST_ID> <SUBSCRIBER_HASH> |
Get member by MD5 hash |
lists create-lists-id-members <LIST_ID> --data '<json>' |
Add member |
lists list-lists-id-merge-fields <LIST_ID> |
List merge fields |
lists create-lists-id-merge-fields <LIST_ID> --data '<json>' |
Add merge field |
lists list-lists-id-segments <LIST_ID> |
List segments |
lists list-list-member-tags <LIST_ID> <SUBSCRIBER_HASH> |
List member tags |
lists create-list-member-tags <LIST_ID> <SUBSCRIBER_HASH> --data '<json>' |
Add/remove member tags |
lists list-lists-id-webhooks <LIST_ID> |
List webhooks |
lists create-lists-id-webhooks <LIST_ID> --data '<json>' |
Add webhook |
Campaigns
| Command |
Description |
campaigns list |
List campaigns |
campaigns get <CAMPAIGN_ID> |
Get campaign info |
campaigns create --data '<json>' |
Create campaign |
campaigns update <CAMPAIGN_ID> --data '<json>' |
Update campaign settings |
campaigns delete <CAMPAIGN_ID> |
Delete campaign |
campaigns send <CAMPAIGN_ID> |
Send campaign immediately |
campaigns schedule <CAMPAIGN_ID> --data '<json>' |
Schedule campaign |
campaigns cancel-send <CAMPAIGN_ID> |
Cancel scheduled send |
campaigns pause <CAMPAIGN_ID> |
Pause RSS campaign |
campaigns resume <CAMPAIGN_ID> |
Resume RSS campaign |
campaigns replicate <CAMPAIGN_ID> |
Duplicate campaign |
campaigns list-content <CAMPAIGN_ID> |
Get campaign content |
campaigns list-send-checklist <CAMPAIGN_ID> |
Pre-send checklist |
Reports
| Command |
Description |
reports list |
List all campaign reports |
reports get <CAMPAIGN_ID> |
Get campaign summary report |
reports list-email-activity <CAMPAIGN_ID> |
Per-subscriber open/click activity |
reports list-click-details <CAMPAIGN_ID> |
Link click breakdown |
reports list-open-details <CAMPAIGN_ID> |
Per-subscriber opens |
reports list-unsubscribed <CAMPAIGN_ID> |
Unsubscribers |
reports list-locations <CAMPAIGN_ID> |
Geographic breakdown |
reports list-domain-performance <CAMPAIGN_ID> |
Per-domain stats |
Automations
| Command |
Description |
automations list |
List automations |
automations get <WORKFLOW_ID> |
Get automation info |
automations create --data '<json>' |
Create automation |
automations pause <WORKFLOW_ID> |
Pause automation |
automations start <WORKFLOW_ID> |
Start automation |
automations archive <WORKFLOW_ID> |
Archive automation |
automations list-emails <WORKFLOW_ID> |
List automation emails |
E-commerce
| Command |
Description |
ecommerce list-ecommerce-stores |
List stores |
ecommerce get <STORE_ID> |
Get store info |
ecommerce create --data '<json>' |
Add store |
ecommerce list-ecommerce-stores-id-orders <STORE_ID> |
List orders |
ecommerce list-ecommerce-stores-id-products <STORE_ID> |
List products |
ecommerce list-ecommerce-stores-id-customers <STORE_ID> |
List customers |
ecommerce list-ecommerce-stores-id-carts <STORE_ID> |
List carts |
ecommerce list-ecommerce-stores-id-promocodes <PROMO_RULE_ID> <STORE_ID> |
List promo codes |
Other Resources
| Group |
Description |
templates |
Email templates (list, get, create, update, delete) |
template-folders |
Template folders |
campaign-folders |
Campaign folders |
file-manager |
Files and folders in the file manager |
landing-pages |
Landing pages (list, create, publish, unpublish) |
sms-campaigns |
SMS campaigns (10 operations) |
surveys |
Surveys (list, get, publish) |
reporting |
Facebook ad and landing page reporting |
search-campaigns |
Search campaigns by query |
search-members |
Search members across all audiences |
batches |
Batch API operations |
batch-webhooks |
Batch operation webhooks |
verified-domains |
Email domain verification |
authorized-apps |
OAuth connected apps |
connected-sites |
Connected site integrations |
conversations |
Inbox conversations |
activity-feed |
Account activity feed |
account-exports |
Account data exports |
JSON Output
All commands support --json at the root level:
# List all audiences as JSON
cli-anything-mailchimp --json lists list
# Get a campaign report as JSON
cli-anything-mailchimp --json reports get abc123def
# Pipe to jq — use the native Mailchimp field name for the resource
cli-anything-mailchimp --json lists list | jq '.lists[].name'
cli-anything-mailchimp --json campaigns list | jq '.campaigns[].id'
Envelope shapes (native Mailchimp API response — use the resource-specific key):
// List endpoints — key matches the resource name (lists, campaigns, members, etc.)
{"lists": [...], "total_items": 42, "_links": [...]}
{"campaigns": [...], "total_items": 10, "_links": [...]}
// Single resource GET / POST / PATCH
{"id": "abc123", "name": "My List", ...}
// DELETE
{"ok": true, "message": "Deleted."}
// Error
{"ok": false, "message": "Resource Not Found: ...", "data": {...}}
Common Agent Patterns
# Get account health
cli-anything-mailchimp --json ping | jq '.health_status'
# List all audience IDs and names
cli-anything-mailchimp --json lists list | jq '.lists[] | {id, name}'
# Find all subscribed members in an audience
cli-anything-mailchimp --json lists list-lists-id-members <list_id> --status subscribed | jq '.members[].email_address'
# Create a campaign and get its send checklist
cli-anything-mailchimp --json campaigns create --data '{"type":"regular","settings":{"subject_line":"Hello","from_name":"Me","reply_to":"me@example.com"}}' | jq '.id'
cli-anything-mailchimp --json campaigns list-send-checklist <campaign_id> | jq '.items[] | select(.result == false)'
# Get unsubscribes for a sent campaign
cli-anything-mailchimp --json reports list-unsubscribed <campaign_id> | jq '.unsubscribes[].email_address'
# Add a member to an audience (subscriber hash = MD5 of lowercased email)
cli-anything-mailchimp --json lists create-members <list_id> --data '{"email_address":"user@example.com","status":"subscribed"}'
# Search for a member across all audiences
cli-anything-mailchimp --json search-members list --query "user@example.com" | jq '.exact_matches.members[]'
Interactive REPL
Run cli-anything-mailchimp with no arguments to enter the REPL:
◆ cli-anything · Mailchimp
v0.1.0
Type help for commands, quit to exit
◆ mailchimp ❯ ping
✓ {"health_status": "Everything's Chimpy!"}
◆ mailchimp ❯ --json lists list
{"lists": [...], "total_items": 3, "_links": [...]}
◆ mailchimp ❯ quit
Notes
- Subscriber hash: Mailchimp identifies members by the MD5 hash of their lowercased email. Compute with
python -c "import hashlib; email='email@example.com'; print(hashlib.md5(email.strip().lower().encode()).hexdigest())".
- Body payloads: All POST/PATCH/PUT commands accept
--data '<json>'. See Mailchimp API docs for the schema of each endpoint.
- Datacenter: Your API key ends in
-us8, -eu2, etc. The CLI extracts this automatically — include it in MAILCHIMP_API_KEY.
- Rate limits: The Marketing API rate-limits at 10 concurrent connections and a rolling per-account limit. For bulk operations, use the
batches group.
1---
2name: "cli-anything-mailchimp"
3description: CLI harness for the Mailchimp Marketing API v3.0 — 303 commands across 30 resource groups (lists, campaigns, reports, automations, ecommerce, templates, and more). Supports JSON output and interactive REPL mode.
4metadata:
5 source: https://skillmd.com/skills/hkuds/cli-anything-mailchimp
6---
7
8# cli-anything-mailchimp
9
10## Identity
11
12An agent-native CLI for the [Mailchimp Marketing API v3.0](https://mailchimp.com/developer/marketing/docs/fundamentals/), built on the [CLI-Anything](https://github.com/HKUDS/CLI-Anything) framework.
13
14## What This CLI Does
15
16- Manage **audiences (lists)** — create, update, delete lists; add/update/archive members; manage merge fields, segments, tags, and webhooks.
17- Run **campaigns** — create, schedule, send, pause, replicate, and analyse email campaigns.
18- Read **reports** — open rates, click rates, bounce stats, unsubscribes, email activity, geographic data.
19- Control **automations** — create and manage automated email workflows.
20- Manage **e-commerce** — stores, orders, customers, products, carts, and promo codes.
21- Use **templates, file manager, landing pages, SMS campaigns, surveys**, and all other Marketing API resources.
22
23## Prerequisites
24
25- Python 3.10+
26- `MAILCHIMP_API_KEY` environment variable set to your API key (including datacenter suffix, e.g. `abc123-us8`)
27
28## Installation
29
30```bash
31# From the CLI-Anything repo (once merged):
32pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=mailchimp/agent-harness
33
34# During development:
35cd mailchimp/agent-harness && pip install -e .
36```
37
38## Command Reference
39
40### Root
41
42| Command | Description |
43|---|---|
44| `cli-anything-mailchimp ping` | Health check — confirms API connectivity |
45| `cli-anything-mailchimp root list` | Get account info |
46| `cli-anything-mailchimp --json <cmd>` | Output any command as JSON |
47| `cli-anything-mailchimp` | Launch interactive REPL |
48
49### Lists (Audiences)
50
51| Command | Description |
52|---|---|
53| `lists list` | List all audiences |
54| `lists get <LIST_ID>` | Get audience info |
55| `lists create --data '<json>'` | Create audience |
56| `lists update <LIST_ID> --data '<json>'` | Update audience |
57| `lists delete <LIST_ID>` | Delete audience |
58| `lists list-lists-id-members <LIST_ID>` | List members |
59| `lists get-lists-id-members-id <LIST_ID> <SUBSCRIBER_HASH>` | Get member by MD5 hash |
60| `lists create-lists-id-members <LIST_ID> --data '<json>'` | Add member |
61| `lists list-lists-id-merge-fields <LIST_ID>` | List merge fields |
62| `lists create-lists-id-merge-fields <LIST_ID> --data '<json>'` | Add merge field |
63| `lists list-lists-id-segments <LIST_ID>` | List segments |
64| `lists list-list-member-tags <LIST_ID> <SUBSCRIBER_HASH>` | List member tags |
65| `lists create-list-member-tags <LIST_ID> <SUBSCRIBER_HASH> --data '<json>'` | Add/remove member tags |
66| `lists list-lists-id-webhooks <LIST_ID>` | List webhooks |
67| `lists create-lists-id-webhooks <LIST_ID> --data '<json>'` | Add webhook |
68
69### Campaigns
70
71| Command | Description |
72|---|---|
73| `campaigns list` | List campaigns |
74| `campaigns get <CAMPAIGN_ID>` | Get campaign info |
75| `campaigns create --data '<json>'` | Create campaign |
76| `campaigns update <CAMPAIGN_ID> --data '<json>'` | Update campaign settings |
77| `campaigns delete <CAMPAIGN_ID>` | Delete campaign |
78| `campaigns send <CAMPAIGN_ID>` | Send campaign immediately |
79| `campaigns schedule <CAMPAIGN_ID> --data '<json>'` | Schedule campaign |
80| `campaigns cancel-send <CAMPAIGN_ID>` | Cancel scheduled send |
81| `campaigns pause <CAMPAIGN_ID>` | Pause RSS campaign |
82| `campaigns resume <CAMPAIGN_ID>` | Resume RSS campaign |
83| `campaigns replicate <CAMPAIGN_ID>` | Duplicate campaign |
84| `campaigns list-content <CAMPAIGN_ID>` | Get campaign content |
85| `campaigns list-send-checklist <CAMPAIGN_ID>` | Pre-send checklist |
86
87### Reports
88
89| Command | Description |
90|---|---|
91| `reports list` | List all campaign reports |
92| `reports get <CAMPAIGN_ID>` | Get campaign summary report |
93| `reports list-email-activity <CAMPAIGN_ID>` | Per-subscriber open/click activity |
94| `reports list-click-details <CAMPAIGN_ID>` | Link click breakdown |
95| `reports list-open-details <CAMPAIGN_ID>` | Per-subscriber opens |
96| `reports list-unsubscribed <CAMPAIGN_ID>` | Unsubscribers |
97| `reports list-locations <CAMPAIGN_ID>` | Geographic breakdown |
98| `reports list-domain-performance <CAMPAIGN_ID>` | Per-domain stats |
99
100### Automations
101
102| Command | Description |
103|---|---|
104| `automations list` | List automations |
105| `automations get <WORKFLOW_ID>` | Get automation info |
106| `automations create --data '<json>'` | Create automation |
107| `automations pause <WORKFLOW_ID>` | Pause automation |
108| `automations start <WORKFLOW_ID>` | Start automation |
109| `automations archive <WORKFLOW_ID>` | Archive automation |
110| `automations list-emails <WORKFLOW_ID>` | List automation emails |
111
112### E-commerce
113
114| Command | Description |
115|---|---|
116| `ecommerce list-ecommerce-stores` | List stores |
117| `ecommerce get <STORE_ID>` | Get store info |
118| `ecommerce create --data '<json>'` | Add store |
119| `ecommerce list-ecommerce-stores-id-orders <STORE_ID>` | List orders |
120| `ecommerce list-ecommerce-stores-id-products <STORE_ID>` | List products |
121| `ecommerce list-ecommerce-stores-id-customers <STORE_ID>` | List customers |
122| `ecommerce list-ecommerce-stores-id-carts <STORE_ID>` | List carts |
123| `ecommerce list-ecommerce-stores-id-promocodes <PROMO_RULE_ID> <STORE_ID>` | List promo codes |
124
125### Other Resources
126
127| Group | Description |
128|---|---|
129| `templates` | Email templates (list, get, create, update, delete) |
130| `template-folders` | Template folders |
131| `campaign-folders` | Campaign folders |
132| `file-manager` | Files and folders in the file manager |
133| `landing-pages` | Landing pages (list, create, publish, unpublish) |
134| `sms-campaigns` | SMS campaigns (10 operations) |
135| `surveys` | Surveys (list, get, publish) |
136| `reporting` | Facebook ad and landing page reporting |
137| `search-campaigns` | Search campaigns by query |
138| `search-members` | Search members across all audiences |
139| `batches` | Batch API operations |
140| `batch-webhooks` | Batch operation webhooks |
141| `verified-domains` | Email domain verification |
142| `authorized-apps` | OAuth connected apps |
143| `connected-sites` | Connected site integrations |
144| `conversations` | Inbox conversations |
145| `activity-feed` | Account activity feed |
146| `account-exports` | Account data exports |
147
148## JSON Output
149
150All commands support `--json` at the root level:
151
152```bash
153# List all audiences as JSON
154cli-anything-mailchimp --json lists list
155
156# Get a campaign report as JSON
157cli-anything-mailchimp --json reports get abc123def
158
159# Pipe to jq — use the native Mailchimp field name for the resource
160cli-anything-mailchimp --json lists list | jq '.lists[].name'
161cli-anything-mailchimp --json campaigns list | jq '.campaigns[].id'
162```
163
164**Envelope shapes** (native Mailchimp API response — use the resource-specific key):
165
166```json
167// List endpoints — key matches the resource name (lists, campaigns, members, etc.)
168{"lists": [...], "total_items": 42, "_links": [...]}
169{"campaigns": [...], "total_items": 10, "_links": [...]}
170
171// Single resource GET / POST / PATCH
172{"id": "abc123", "name": "My List", ...}
173
174// DELETE
175{"ok": true, "message": "Deleted."}
176
177// Error
178{"ok": false, "message": "Resource Not Found: ...", "data": {...}}
179```
180
181## Common Agent Patterns
182
183```bash
184# Get account health
185cli-anything-mailchimp --json ping | jq '.health_status'
186
187# List all audience IDs and names
188cli-anything-mailchimp --json lists list | jq '.lists[] | {id, name}'
189
190# Find all subscribed members in an audience
191cli-anything-mailchimp --json lists list-lists-id-members <list_id> --status subscribed | jq '.members[].email_address'
192
193# Create a campaign and get its send checklist
194cli-anything-mailchimp --json campaigns create --data '{"type":"regular","settings":{"subject_line":"Hello","from_name":"Me","reply_to":"me@example.com"}}' | jq '.id'
195cli-anything-mailchimp --json campaigns list-send-checklist <campaign_id> | jq '.items[] | select(.result == false)'
196
197# Get unsubscribes for a sent campaign
198cli-anything-mailchimp --json reports list-unsubscribed <campaign_id> | jq '.unsubscribes[].email_address'
199
200# Add a member to an audience (subscriber hash = MD5 of lowercased email)
201cli-anything-mailchimp --json lists create-members <list_id> --data '{"email_address":"user@example.com","status":"subscribed"}'
202
203# Search for a member across all audiences
204cli-anything-mailchimp --json search-members list --query "user@example.com" | jq '.exact_matches.members[]'
205```
206
207## Interactive REPL
208
209Run `cli-anything-mailchimp` with no arguments to enter the REPL:
210
211```
212◆ cli-anything · Mailchimp
213 v0.1.0
214 Type help for commands, quit to exit
215
216◆ mailchimp ❯ ping
217 ✓ {"health_status": "Everything's Chimpy!"}
218
219◆ mailchimp ❯ --json lists list
220{"lists": [...], "total_items": 3, "_links": [...]}
221
222◆ mailchimp ❯ quit
223```
224
225## Notes
226
227- **Subscriber hash**: Mailchimp identifies members by the MD5 hash of their lowercased email. Compute with `python -c "import hashlib; email='email@example.com'; print(hashlib.md5(email.strip().lower().encode()).hexdigest())"`.
228- **Body payloads**: All POST/PATCH/PUT commands accept `--data '<json>'`. See [Mailchimp API docs](https://mailchimp.com/developer/marketing/api/) for the schema of each endpoint.
229- **Datacenter**: Your API key ends in `-us8`, `-eu2`, etc. The CLI extracts this automatically — include it in `MAILCHIMP_API_KEY`.
230- **Rate limits**: The Marketing API rate-limits at 10 concurrent connections and a rolling per-account limit. For bulk operations, use the `batches` group.