cli-anything-mailchimp 实战指南将 Mailchimp Marketing API v3.0 封装为 303 条 Agent 原生 CLI 命令【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文围绕 CLI-Anything 生态中面向 Mailchimp Marketing API v3.0 的 CLI 封装层cli-anything-mailchimp完整讲解其安装、鉴权、命令分层、JSON 输出与交互式 REPL 等核心用法并结合仓库内源码解析数据中心的自动推导、HTTP 客户端封装、分页机制与订阅者哈希算法等底层原理。读完本文你将能够直接以命令行或交由 AI Agent管理受众列表、邮件营销活动、报告、自动化流程与电商数据并把任意接口输出管道化到jq等下游工具做进一步处理。一、这是什么Agent 原生的 Mailchimp 命令行入口cli-anything-mailchimp是构建在 CLI-Anything 框架之上的 Mailchimp Marketing API v3.0 CLI 封装层其核心定位见 SKILL.md 的 frontmatter 描述是覆盖 30 个资源组、共 303 条命令的 CLI 工具支持 JSON 输出与交互式 REPL 模式。所谓 “agent-native”是指这套 CLI 面向 AI Agent 与脚本场景做了刻意设计鉴权只用环境变量、请求体统一用--data传入 JSON、集合类命令保留 Mailchimp 原生返回结构使 Agent 无需记住大量细碎参数即可拼装合法请求。它管理的主要能力包括受众Audiences/Lists创建、更新、删除列表增改、归档成员管理 merge fields、细分segments、标签与 webhook营销活动Campaigns创建、排期、立即发送、暂停、复制与解析邮件营销活动报告Reports打开率、点击率、退信统计、退订、邮件活动与地理位置分布自动化Automations创建与管理自动化邮件工作流电商E-commerce商店、订单、客户、产品、购物车与促销码以及模板、文件管理器、落地页、SMS 营销活动、问卷等其余 Marketing API 资源。需要特别说明的是命令体量并非空谈——仓库目录 commands/ 下按 Swagger 规范 tag 拆分了 30 个命令模块commands/init.py 通过ALL_GROUPS统一聚合最终在 mailchimp_cli.py 中被循环注册到 Click 根命令上# Register all generated resource groups for _group in ALL_GROUPS: cli.add_command(_group)每条命令都对应 Swagger 规范中的一个端点操作命令文本均由 _codegen/generate.py 从官方 Swagger 2.0 规范自动生成后提交入库因此终端用户无需下载规范即可享受完整的--help。二、环境准备与安装2.1 前置条件Python 3.10MAILCHIMP_API_KEY环境变量需包含数据中心后缀形如abc123-us8。在 core/client.py 中可看到CLI 通过_server_prefix()从 API Key 末段自动解析数据中心后缀若 Key 不含-会直接抛出明确错误提示。因此 Key 中必须带上数据中心后缀这也是鉴权唯一的信息源——本项目遵循 CLI-Anything 约定不读取任何配置文件。2.2 安装方式# 从 CLI-Anything 仓库安装该子目录方式 pip install githttps://github.com/HKUDS/CLI-Anything.git#subdirectorymailchimp/agent-harness # 开发模式安装 cd mailchimp/agent-harness pip install -e .仓库内的 setup.py 声明了完整的 Python 包结构与入口点。安装完成后设置环境变量即可使用export MAILCHIMP_API_KEYyour-key-datacenter从 mailchimp_cli.py 的源码可印证CLI 在需要发起请求时通过get_client()实例化客户端一旦缺少 Key 即抛出MailchimpAuthError并以非零码退出见 client.py避免静默失败。三、鉴权与连接层底层原理后端连接信息详见 MAILCHIMP.md属性值API 基地址https://dc.api.mailchimp.com/3.0认证方式HTTP Basic——用户名为任意字符串anystring密码为 API KeyKey 格式random-datacenter如abc123-us8规范来源mailchimp/mailchimp-client-lib-codegen的spec/marketing.jsonSwagger 2.0源码层面core/client.py 的MailchimpClient.__init__做了三件事从参数或MAILCHIMP_API_KEY环境变量读取 Key用_server_prefix()切出-后的数据中心后缀如us8、eu2拼出完整基地址创建requests.Session统一设置Basic Auth((anystring, key))与User-Agent: cli-anything-mailchimp/0.1.0。错误处理集中在_raise()见 client.py非 2xx 响应会解析 Mailchimp 标准 Problem Detail JSONtitle/detail并抛出带状态码、标题、详情与原始报文的MailchimpError无法解析 JSON 时则退化为状态码 响应文本前 200 字符。四、命令体系全景根命令、资源组与 303 条操作4.1 根命令命令说明cli-anything-mailchimp ping健康检查确认 API 连通性cli-anything-mailchimp root list获取账户信息cli-anything-mailchimp --json cmd将任意命令以 JSON 输出cli-anything-mailchimp进入交互式 REPL根命令本身是一个 Click 组mailchimp_cli.pyinvoke_without_commandTrue意味着不带子命令执行时会启动 REPL--json是一个根级开关通过模块级变量output.USE_JSON切换全部子命令的输出行为。4.2 资源组规模一览命令层级整理自 MAILCHIMP.md 的命令层级树cli-anything-mailchimp [--json] [--version] │ ├── ping # GET /ping — 健康检查 ├── root # GET / — 账户信息 │ ├── lists # 66 个操作audiences、成员、merge fields、segments、tags、webhooks ├── campaigns # 22 个操作 ├── reports # 22 个操作 — 已发送营销活动分析 ├── automations # 18 个操作 ├── ecommerce # 60 个操作 — stores、orders、products、carts、promo codes ├── templates # 6 个操作 ├── template-folders # 5 个操作 ├── campaign-folders # 5 个操作 ├── file-manager # 11 个操作 ├── reporting # 12 个操作 — Facebook / 落地页报告 ├── landing-pages # 8 个操作 ├── sms-campaigns # 10 个操作 ├── surveys # 3 个操作 ├── audiences # 4 个操作 ├── batch-webhooks # 5 个操作 ├── batches # 4 个操作 — 批量 API ├── connected-sites # 5 个操作 ├── contacts # 4 个操作 ├── conversations # 4 个操作 ├── customer-journeys # 1 个操作 ├── facebook-ads # 2 个操作 ├── verified-domains # 5 个操作 ├── authorized-apps # 2 个操作 ├── activity-feed # 1 个操作 ├── account-export # 1 个操作 ├── account-exports # 2 个操作 ├── search-campaigns # 1 个操作 └── search-members # 1 个操作4.3 Lists受众常用命令命令说明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列出 merge fieldslists create-lists-id-merge-fields LIST_ID --data json添加 merge fieldlists 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列出 webhooklists create-lists-id-webhooks LIST_ID --data json添加 webhook4.4 Campaigns营销活动常用命令命令说明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发送前检查清单4.5 Reports报告常用命令命令说明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按域名统计4.6 Automations自动化常用命令命令说明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列出自动化邮件4.7 E-commerce电商常用命令命令说明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列出促销码4.8 其余资源组资源组说明templates邮件模板增删改查template-folders模板文件夹campaign-folders营销活动文件夹file-manager文件管理器中的文件与文件夹landing-pages落地页列表、创建、发布、取消发布sms-campaignsSMS 营销活动10 个操作surveys问卷列表、获取、发布reportingFacebook 广告与落地页报告search-campaigns按查询词搜索营销活动search-members跨全部受众搜索成员batches批量 API 操作batch-webhooks批量操作 webhookverified-domains邮件域名验证authorized-appsOAuth 已授权应用connected-sites已连接的站点集成conversations收件箱会话activity-feed账户活动流account-exports账户数据导出五、命令生成的源码级细节参数如何进入 HTTP 请求阅读任意生成的命令模块例如 ping.py可以归纳出统一的代码生成模板路径参数如{LIST_ID}、{CAMPAIGN_ID}被生成为必填的位置参数Clickargument命令保持简洁查询参数被生成为可选 flag其中集合类命令会忠实还原 Mailchimp 规范中的--count、--offset、--fields、--exclude-fields等参数请求体统一由--data json传入经_parse_json_option()用json.loads解析非法 JSON 会以 ClickBadParameter形式给出可读报错所有未显式建模的查询参数可用--extra-params {key:value}兜底。以 lists.py 的lists list为例其生成的查询参数包括--count默认 10、最大 1000、--offset、时间窗过滤--before-date-created/--since-date-created/--before-campaign-last-sent/--since-campaign-last-sent均使用 ISO 8601 格式2015-10-21T15:41:3600:00、--email、--sort-field、--sort-dir、--has-ecommerce-store、--include-total-contacts等。真正发起请求前所有取值为None的键会被剔除只把用户显式提供的参数随GET请求发出。在 HTTP 层client.py 提供了get / post / patch / put / delete五个薄封装统一处理 URL 拼接、30 秒默认超时_DEFAULT_TIMEOUT 30、错误抛出与 JSON 反序列化post对 204 空响应会返回空字典以兼容无内容端点。六、JSON 输出与管道化6.1 全局--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实现上utils/output.py 维护模块级USE_JSON标志根命令解析--json后直接写入该标志随后_out()依据标志决定输出json.dumps(data, indent2)还是人工可读的着色键值对/列表。单对象走_print_dict嵌套层级递归缩进集合走_print_list字典内的列表字段以[N items]摘要呈现保证命令行阅读友好。6.2 信封结构Envelope ShapesCLI 直接透传 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: {...}}对应源码中删除操作在 client.py 成功时返回{ok: True}再由_out_ok()包装为{ok: true, message: Deleted.}错误则由_out_err()输出{ok: false, message: title: detail, data: mailchimp-problem-detail}到stderr并退出码为 1见 output.py方便外层脚本区分正常结果与失败。6.3 人类可读模式未加--json时删除/变更类操作打印绿色勾选✓ message错误打印红色叉号✗ HTTP status: title。注意在 JSON 模式下错误报文写入 stderr、正常结果写入 stdout这为 shell 管道组合留出了干净的输出通道。七、面向 Agent 的常用操作模式以下是 SKILL.md 中沉淀的、可直接复制的 Agent 调用范式# 获取账户健康状态 cli-anything-mailchimp --json ping | jq .health_status # 列出全部受众 ID 与名称 cli-anything-mailchimp --json lists list | jq .lists[] | {id, name} # 找出某受众中所有 subscribed 状态的成员 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:meexample.com}} | 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 # 向受众添加成员subscriber hash 小写邮箱的 MD5 cli-anything-mailchimp --json lists create-members list_id --data {email_address:userexample.com,status:subscribed} # 跨全部受众搜索成员 cli-anything-mailchimp --json search-members list --query userexample.com | jq .exact_matches.members[]这些模式之所以对 Agent 友好与“设计决策”密不可分见 MAILCHIMP.md路径参数转位置参数{list_id}、{campaign_id}等直接成为必填位置参数命令无冗余请求体统一走--dataJSON避免了为每个字段生成几十个 flagAgent 可直接构造 JSON 载荷响应透传原生结构jq路径与官方 API 文档一致降低了心智负担--extra-params逃生舱未建模的查询参数仍可完整传达。八、分页默认单页、可选自动遍历Mailchimp 集合端点使用count/offset分页。仓库在 core/pagination.py 中提供两种工具collect(client, path, result_key, ...)默认只取单页尊重调用方传入的count/offset返回(items, total_items)若调用方未指定则取一页默认页大小 1000paginate(client, path, result_key, ...)生成器式逐页拉取全部条目每次请求携带countpage_size并递增offset直到取空页或offset total_items时停止。从 MAILCHIMP.md 的输出策略可知生成式命令默认不会自动抓取全部分页而是透出 Mailchimp 原生count与offset参数由使用者控制。因此需要“全量拉取”的脚本可以在单次 CLI 调用之上自行循环或使用仓库中的paginate()逻辑作为自定义脚本的参考实现。九、交互式 REPL不带任何参数执行cli-anything-mailchimp即进入 REPL入口见 mailchimp_cli.py底层基于 prompt_toolkit借助 utils/repl_skin.py按 CLI-Anything 贡献规范从cli-anything-plugin/repl_skin.py原样复制渲染界面◆ cli-anything · Mailchimp v0.1.0 Type help for commands, quit to exit ◆ mailchimp ❯ ping ✓ {health_status: Everythings Chimpy!} ◆ mailchimp ❯ --json lists list {lists: [...], total_items: 3, _links: [...]} ◆ mailchimp ❯ quitREPL 内直接复用 Click 命令行解析输入经shlex.split分词后以standalone_modeFalse调用cli.main()从而支持--json前缀、任意子命令与参数quit/exit/q退出help则遍历ALL_GROUPS汇总出每组一句话帮助。通过Ctrl-C可随时中断回到提示符。十、关键 Notes哈希、载荷与限流10.1 订阅者哈希Subscriber HashMailchimp 用“小写邮箱的 MD5”作为成员标识符。仓库在 client.py 中提供了与官方实现一致的参考函数def subscriber_hash(email: str) - str: MD5 hash of the lowercased email — Mailchimps subscriber identifier. return hashlib.md5(email.strip().lower().encode()).hexdigest()命令行下可这样现场计算python -c import hashlib; emailemailexample.com; print(hashlib.md5(email.strip().lower().encode()).hexdigest())10.2 Body 载荷与模型字段所有 POST/PATCH/PUT 命令都接受--data json。各端点的字段 schema 以 Mailchimp Marketing API 官方文档为准CLI 不做二次校验——这既保持了轻量也把参数校验的职责明确交给 API 侧。10.3 数据中心与限流数据中心Key 后缀-us8、-eu2等会被_server_prefix()自动提取并决定请求目标域名因此务必把后缀写进MAILCHIMP_API_KEY限流Marketing API 限制约 10 个并发连接且存在滚动窗口的账户级配额。对大批量写入场景应使用batches资源组提交批量任务而非并发循环逐条调用。十一、测试与验证路径若希望进一步确认底层行为仓库提供了两处可阅读的测试入口目录见 tests/TEST.md测试说明test_core.py无需 API Key 的单元测试覆盖数据中心解析、订阅者哈希、客户端初始化等纯逻辑test_full_e2e.py以真实 API Key 为前置条件的 9 条端到端测试。其中subscriber_hash、_server_prefix属于典型的“无外部依赖即可验证”的逻辑阅读测试可以快速建立对 CLI 行为边界的直觉。运行测试时请按 setup.py 与测试文件中标注的方式准备环境与 Key切勿在 CI 或共享环境硬编码凭据。十二、结语一个可直接落地的 Agent 化 Mailchimp 工具箱cli-anything-mailchimp的价值在于把 303 个 HTTP 端点收敛为一个统一命令空间统一鉴权环境变量、统一输出原生 JSON 信封、统一交互REPL 一次性命令双模。无论你是在编写营销自动化脚本、做邮件数据报表分析还是让 LLM Agent 直接操作 Mailchimp 账户都可以参照本文的鉴权设置、命令分层、--json管道范式与分页/哈希等底层细节快速落地——再配合--json ... | jq的解析链路整套 API 就可以像本地工具一样被自由组合与编排。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考