cli-anything-mailchimp

cli-anything-mailchimp 是做什麼的？

身分識別

以 Agent 為核心的命令列工具，用於 Mailchimp Marketing API v3.0，建構於 CLI-Anything 框架之上。

此 CLI 的功能

• 管理 受眾（名單） — 建立、更新、刪除名單；新增/更新/封存成員；管理合併欄位、區隔、標籤與 Webhook。
• 執行 活動 — 建立、排程、發送、暫停、複製與分析電子郵件活動。
• 讀取 報表 — 開啟率、點擊率、退信統計、取消訂閱、電子郵件活動、地理資料。
• 控制 自動化 — 建立與管理自動化電子郵件工作流程。
• 管理 電子商務 — 商店、訂單、客戶、產品、購物車與促銷代碼。
• 使用 範本、檔案管理員、登陸頁面、簡訊活動、調查 及所有其他 Marketing API 資源。

前置需求

• Python 3.10+
• 設定 MAILCHIMP_API_KEY 環境變數為您的 API 金鑰（包含資料中心後綴，例如 abc123-us8）

安裝

# 從 CLI-Anything 儲存庫（合併後）：
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=mailchimp/agent-harness

# 開發期間：
cd mailchimp/agent-harness && pip install -e .

指令參考

根層級

指令	說明
cli-anything-mailchimp ping	健康檢查 — 確認 API 連線
cli-anything-mailchimp root list	取得帳號資訊
cli-anything-mailchimp --json <cmd>	輸出任何指令的 JSON 結果
cli-anything-mailchimp	啟動互動式 REPL

名單（受眾）

指令	說明
lists list	列出所有受眾
lists get <LIST_ID>	取得受眾資訊
lists create --data '<json>'	建立受眾
lists update <LIST_ID> --data '<json>'	更新受眾
lists delete <LIST_ID>	刪除受眾
lists list-lists-id-members <LIST_ID>	列出成員
lists get-lists-id-members-id <LIST_ID> <SUBSCRIBER_HASH>	透過 MD5 雜湊取得成員
lists create-lists-id-members <LIST_ID> --data '<json>'	新增成員
lists list-lists-id-merge-fields <LIST_ID>	列出合併欄位
lists create-lists-id-merge-fields <LIST_ID> --data '<json>'	新增合併欄位
lists list-lists-id-segments <LIST_ID>	列出區隔
lists list-list-member-tags <LIST_ID> <SUBSCRIBER_HASH>	列出成員標籤
lists create-list-member-tags <LIST_ID> <SUBSCRIBER_HASH> --data '<json>'	新增/移除成員標籤
lists list-lists-id-webhooks <LIST_ID>	列出 Webhook
lists create-lists-id-webhooks <LIST_ID> --data '<json>'	新增 Webhook

活動

指令	說明
campaigns list	列出活動
campaigns get <CAMPAIGN_ID>	取得活動資訊
campaigns create --data '<json>'	建立活動
campaigns update <CAMPAIGN_ID> --data '<json>'	更新活動設定
campaigns delete <CAMPAIGN_ID>	刪除活動
campaigns send <CAMPAIGN_ID>	立即發送活動
campaigns schedule <CAMPAIGN_ID> --data '<json>'	排程活動
campaigns cancel-send <CAMPAIGN_ID>	取消已排程的發送
campaigns pause <CAMPAIGN_ID>	暫停 RSS 活動
campaigns resume <CAMPAIGN_ID>	恢復 RSS 活動
campaigns replicate <CAMPAIGN_ID>	複製活動
campaigns list-content <CAMPAIGN_ID>	取得活動內容
campaigns list-send-checklist <CAMPAIGN_ID>	發送前檢查清單

報表

指令	說明
reports list	列出所有活動報表
reports get <CAMPAIGN_ID>	取得活動摘要報表
reports list-email-activity <CAMPAIGN_ID>	每位訂閱者的開啟/點擊活動
reports list-click-details <CAMPAIGN_ID>	連結點擊細項
reports list-open-details <CAMPAIGN_ID>	每位訂閱者的開啟次數
reports list-unsubscribed <CAMPAIGN_ID>	取消訂閱者
reports list-locations <CAMPAIGN_ID>	地理位置細項
reports list-domain-performance <CAMPAIGN_ID>	各網域統計

自動化

指令	說明
automations list	列出自動化流程
automations get <WORKFLOW_ID>	取得自動化資訊
automations create --data '<json>'	建立自動化流程
automations pause <WORKFLOW_ID>	暫停自動化流程
automations start <WORKFLOW_ID>	啟動自動化流程
automations archive <WORKFLOW_ID>	封存自動化流程
automations list-emails <WORKFLOW_ID>	列出自動化電子郵件

電子商務

指令	說明
ecommerce list-ecommerce-stores	列出商店
ecommerce get <STORE_ID>	取得商店資訊
ecommerce create --data '<json>'	新增商店
ecommerce list-ecommerce-stores-id-orders <STORE_ID>	列出訂單
ecommerce list-ecommerce-stores-id-products <STORE_ID>	列出產品
ecommerce list-ecommerce-stores-id-customers <STORE_ID>	列出客戶
ecommerce list-ecommerce-stores-id-carts <STORE_ID>	列出購物車
ecommerce list-ecommerce-stores-id-promocodes <PROMO_RULE_ID> <STORE_ID>	列出促銷代碼

其他資源

群組	說明
templates	電子郵件範本（列出、取得、建立、更新、刪除）
template-folders	範本資料夾
campaign-folders	活動資料夾
file-manager	檔案管理員中的檔案與資料夾
landing-pages	登陸頁面（列出、建立、發佈、取消發佈）
sms-campaigns	簡訊活動（10 種操作）
surveys	調查（列出、取得、發佈）
reporting	Facebook 廣告與登陸頁面報表
search-campaigns	依查詢搜尋活動
search-members	跨所有受眾搜尋成員
batches	批次 API 操作
batch-webhooks	批次操作 Webhook
verified-domains	電子郵件網域驗證
authorized-apps	OAuth 連接的應用程式
connected-sites	已連接的網站整合
conversations	收件匣對話
activity-feed	帳號活動摘要
account-exports	帳號資料匯出

JSON 輸出

所有指令都支援在根層級使用 --json 旗標：

# 以 JSON 列出所有受眾
cli-anything-mailchimp --json lists list

# 以 JSON 取得活動報表
cli-anything-mailchimp --json reports get abc123def

# 管線傳遞給 jq — 使用該資源的原生 Mailchimp 欄位名稱
cli-anything-mailchimp --json lists list | jq '.lists[].name'
cli-anything-mailchimp --json campaigns list | jq '.campaigns[].id'

回傳結構（原生 Mailchimp API 回應 — 使用資源特定金鑰）：

// 列出端點 — 金鑰與資源名稱相符（lists、campaigns、members 等）
{"lists": [...], "total_items": 42, "_links": [...]}
{"campaigns": [...], "total_items": 10, "_links": [...]}

// 單一資源 GET / POST / PATCH
{"id": "abc123", "name": "My List", ...}

// DELETE
{"ok": true, "message": "Deleted."}

// 錯誤
{"ok": false, "message": "Resource Not Found: ...", "data": {...}}

常見 Agent 使用模式

# 檢查帳號健康狀態
cli-anything-mailchimp --json ping | jq '.health_status'

# 列出所有受眾 ID 與名稱
cli-anything-mailchimp --json lists list | jq '.lists[] | {id, name}'

# 在受眾中尋找所有已訂閱的成員
cli-anything-mailchimp --json lists list-lists-id-members <list_id> --status subscribed | jq '.members[].email_address'

# 建立活動並取得其發送前檢查清單
cli-anything-mailchimp --json campaigns create --data '{"type":"regular","settings":{"subject_line":"Hello","from_name":"Me","reply_to":"[email protected]"}}' | jq '.id'
cli-anything-mailchimp --json campaigns list-send-checklist <campaign_id> | jq '.items[] | select(.result == false)'

# 取得已發送活動的取消訂閱者
cli-anything-mailchimp --json reports list-unsubscribed <campaign_id> | jq '.unsubscribes[].email_address'

# 新增成員至受眾（訂閱者雜湊 = 小寫電子郵件的 MD5）
cli-anything-mailchimp --json lists create-members <list_id> --data '{"email_address":"[email protected]","status":"subscribed"}'

# 跨所有受眾搜尋成員
cli-anything-mailchimp --json search-members list --query "[email protected]" | jq '.exact_matches.members[]'

互動式 REPL

執行 cli-anything-mailchimp 而不帶任何參數即可進入 REPL：

◆  cli-anything · Mailchimp
   v0.1.0
   輸入 help 檢視指令，輸入 quit 離開

◆ mailchimp ❯ ping
  ✓ {"health_status": "Everything's Chimpy!"}

◆ mailchimp ❯ --json lists list
{"lists": [...], "total_items": 3, "_links": [...]}

◆ mailchimp ❯ quit

備註

• 訂閱者雜湊：Mailchimp 透過成員小寫電子郵件的 MD5 雜湊來識別成員。可使用 python -c "import hashlib; email='[email protected]'; print(hashlib.md5(email.strip().lower().encode()).hexdigest())" 計算。
• 主體內容：所有 POST/PATCH/PUT 指令都接受 --data '<json>'。請參閱 Mailchimp API 文件 了解每個端點的結構。
• 資料中心：您的 API 金鑰結尾為 -us8、-eu2 等。CLI 會自動提取此資訊 — 請將其包含在 MAILCHIMP_API_KEY 中。
• 速率限制：Marketing API 限制為 10 個並行連線與每個帳號的滾動限制。對於批量操作，請使用 batches 群組。