pp-multimail

MultiMail — Printing Press CLI

前提条件：安装 CLI

此 Skill 通过 multimail-pp-cli 二进制文件运行。**调用此 Skill 中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install multimail --cli-only
   

2. 验证：multimail-pp-cli --version
3. 确保报告的安装目录位于将调用此 Skill 的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用 Go 直接安装（需要 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/multimail/cmd/multimail-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。在验证成功之前，请勿继续执行 Skill 命令。

何时使用此 CLI

需要管理 Agent 邮件群组、处理监督队列、监控信任阶梯进展、跨邮箱搜索以及跟踪收件箱健康状况时，请使用 multimail-pp-cli。它将 MultiMail 的分级自治模式转化为日常运维工作流。

不适用场景

以下情况请勿使用此 CLI：

• 发送大批量营销邮件——MultiMail 用于 Agent 与人类之间的通信，而非群发邮件
• 管理非 MultiMail 邮件账户（Gmail、Outlook）——请使用 better-email-mcp 或原生 MCP 工具
• 实时邮件流——如需亚秒级事件传递，请直接使用 MultiMail Webhook
• 更改账户账单信息——请使用 MultiMail 控制面板管理付款和套餐

独特功能

其他任何用于此 API 的工具都不具备这些功能。

原生 Agent 基础设施

• fleet health — 一条命令即可获取账户范围的健康状况快照：邮箱数量、监督队列深度、Webhook 投递率、域名验证状态、用量与套餐限额的对比。

  如果 Agent 在发送邮件前需要确认其 MultiMail 集成是否健康，一条命令即可替代对 5 个独立端点的检查。

  multimail-pp-cli fleet health --json --agent --select mailboxes.total,oversight.pending_count,webhooks.success_rate
  

• oversight bulk-decide — 一条命令即可根据筛选条件（邮箱、发件人或邮件时间）批准或拒绝所有待处理邮件。

  如果 Agent 的测试队列中有 20 封待处理邮件，一条命令即可全部处理，无需逐一调用 20 次批准操作。

  multimail-pp-cli oversight bulk-decide --approve --mailbox support-agent --json
  

• oversight velocity — 查看整个邮件群组中各邮箱的批准/拒绝率和决策延迟中位数。

  如果 Agent 发送的邮件卡在审批队列中，此功能可找出哪个邮箱的操作员是瓶颈。

  multimail-pp-cli oversight velocity --json --days 7
  

• trust status — 查看整个邮件群组中每个邮箱的监督模式、当前级别的持续时间以及升级资格。

  在申请信任升级前，Agent 应了解哪些邮箱已准备就绪，以及哪些邮箱处于当前级别的时间最长。

  multimail-pp-cli trust status --json --agent --select name,oversight_mode,time_at_level
  

• trust timeline — 按时间顺序查看每个邮箱监督模式的变更记录，包括时间戳和触发变更的人。

  在评估是否申请信任升级时，Agent 需要展示其在每个级别负责任运行的历史记录。

  multimail-pp-cli trust timeline --mailbox support-agent --json
  

• emails send-and-wait — 发送邮件并阻塞等待回复或超时——一条命令即可完成 Agent 测试循环。

  如果 Agent 需要在一个工作流步骤中发送邮件并处理回复，此功能可取代手动发送、轮询和读取的循环。

  multimail-pp-cli emails send-and-wait --mailbox test-agent --to [email protected] --subject 'Test' --body 'Hello' --timeout 5m --json
  

会不断积累的本地状态

• mailboxes allowlist coverage — 查看近期收件人中，已被允许列表模式覆盖和受到限制的比例。

  在添加允许列表条目之前，Agent 应了解哪些收件人已被覆盖，以及哪些收件人造成的限制摩擦最大。

  multimail-pp-cli mailboxes allowlist coverage --mailbox primary --days 30 --json --agent --select pattern,match_count,percentage
  

• inbox health — 每个邮箱的健康状况快照：未读数量、最早未读邮件的等待时间、回复率和会话深度。

  监控自身收件箱健康状况的 Agent 可以在运营者发现之前，检测到自己是否开始无法及时回复。

  multimail-pp-cli inbox health --json --agent --select mailbox,unread_count,oldest_unread_age,reply_rate
  

• threads stale — 列出 N 天内没有收到回复的对话会话，找出被搁置的对话。

  被搁置的对话会话属于面向客户的服务失败；这是 Agent 的早期预警系统。

  multimail-pp-cli threads stale --days 3 --json --agent --select thread_id,subject,last_reply_age,mailbox
  

• audit compliance — 跨实体合规报告：绕过监督的次数、每个邮箱的批准／拒绝次数和决策延迟百分位数。

  当审计员需要核实 Agent 是否在获批的信任级别内运行时，此工具可取代手动关联日志。

  multimail-pp-cli audit compliance --days 30 --json
  

• webhooks health — 每个 webhook 的成功率、失败次数、上次投递时间戳和连续失败次数。

  当 Agent 的实时事件流水线依赖 webhook 时，此工具可以在静默故障累积之前显示投递健康状况。

  multimail-pp-cli webhooks health --json --agent --select webhook_id,url,success_rate,consecutive_failures
  

命令参考

account — 管理账户

• multimail-pp-cli account create — 需要通过已求解的工作量证明挑战。创建待处理的注册，并发送确认邮件。
• multimail-pp-cli account create-challenge — 返回 ALTCHA 挑战。求解后，将解作为 pow_solution 包含在 POST /v1/account 中。
• multimail-pp-cli account create-resendconfirmation — 公开端点（无需身份验证）。为未确认的账户重新发送带有新验证码的激活邮件。
• multimail-pp-cli account delete — 永久删除所有租户数据（邮箱、电子邮件、API 密钥、用量、审计日志）。释放 slug 以便重新注册。
• multimail-pp-cli account list — 获取当前租户信息和用量
• multimail-pp-cli account update — 更新租户设置

admin — 管理管理员

• multimail-pp-cli admin — 仅限管理员使用。创建新的 API 密钥，并通过电子邮件发送给租户的监督邮箱。

agent — 管理 Agent

• multimail-pp-cli agent create — 使用 verified_email 身份声明启动 Agent 注册。
• multimail-pp-cli agent create-auth — 通过验证 claim_token 和 OTP 完成 auth.md 注册。
• multimail-pp-cli agent list — 面向用户的页面，显示用于 Agent 注册的 6 位 OTP。该页面链接自验证邮件。

api-keys — 管理 API 密钥

• multimail-pp-cli api-keys create — 需要 admin 权限范围。原始密钥只会在响应中返回一次。
• multimail-pp-cli api-keys delete — 需要 admin 权限范围。首次调用返回 202 和 pending_approval；使用 approval_code 重新发送以完成操作。
• multimail-pp-cli api-keys list — 需要 admin 权限范围。返回密钥前缀、权限范围和元数据。
• multimail-pp-cli api-keys update — 更新 API 密钥名称或权限范围

approve — 管理批准

• multimail-pp-cli approve create — 处理来自托管页面的批准／拒绝操作
• multimail-pp-cli approve get — 呈现用于监督决策的托管批准页面

audit-log — 管理审计日志

• multimail-pp-cli audit-log — 返回带游标分页的审计日志条目。需要 admin 权限范围。

auth-md — 管理 auth md

• multimail-pp-cli auth-md — 返回一份 Markdown 文档，介绍 MultiMail 的 Agent 注册流程、信任阶梯和权限范围模型。

billing — 管理账单

• multimail-pp-cli billing create — 需要管理员权限范围。
• multimail-pp-cli billing create-checkout — 创建用于升级套餐的 Stripe 结账会话
• multimail-pp-cli billing create-coinbasewebhook — Coinbase Commerce webhook 处理程序（公开，已验证签名）
• multimail-pp-cli billing create-cryptocheckout — 创建 Coinbase Commerce 结账会话（加密货币支付）
• multimail-pp-cli billing create-portal — 需要管理员权限范围。
• multimail-pp-cli billing create-pricingcheckout — 创建未激活的租户，配置默认邮箱，并返回 Stripe 结账 URL。
• multimail-pp-cli billing create-stripewebhook — Stripe webhook 处理程序（公开，已验证签名）
• multimail-pp-cli billing list — 公开端点。返回定价结账时存储的 API 密钥，然后将其删除。

confirm — 管理确认

• multimail-pp-cli confirm create — JSON 响应包含：status、name、oversight_mode、api_key、mailbox_id、mailbox_address、oversight_email、use_case。
• multimail-pp-cli confirm get — 重定向到已预填代码的前端确认页面
• multimail-pp-cli confirm list — 重定向到 multimail.dev/confirm 上的前端确认页面

contacts — 管理联系人

• multimail-pp-cli contacts create — 将联系人添加到通讯录。需要发送权限范围。
• multimail-pp-cli contacts delete — 需要管理员权限范围。
• multimail-pp-cli contacts list — 按姓名或邮箱搜索通讯录。省略查询条件即可列出所有联系人。需要读取权限范围。

data_export — 管理数据导出

• multimail-pp-cli data-export — 需要管理员权限范围。每小时最多请求 1 次。

domains — 管理域名

• multimail-pp-cli domains create — 添加自定义域名（仅限 Pro/Scale）
• multimail-pp-cli domains delete — 删除自定义域名
• multimail-pp-cli domains get — 获取自定义域名详情
• multimail-pp-cli domains list — 需要管理员权限范围。

emails — 管理邮件

• multimail-pp-cli emails — 需要读取权限范围。

funnel — 管理转化漏斗

• multimail-pp-cli funnel — 通过 navigator.sendBeacon 发送定价页面信标，以跟踪注册弹窗中的打开、提交和错误事件。

health — 管理健康检查

• multimail-pp-cli health — 验证 D1 和 R2 的连接情况。无需身份验证。

mailboxes — 管理邮箱

• multimail-pp-cli mailboxes create — 需要管理员权限范围。
• multimail-pp-cli mailboxes delete — 需要管理员权限范围。
• multimail-pp-cli mailboxes list — 需要读取权限范围。
• multimail-pp-cli mailboxes update — 需要管理员权限范围。此处只能降低监督模式级别；升级需要通过升级流程完成。

operator — 管理操作员

• multimail-pp-cli operator create — 需要管理员权限范围。清除操作员会话 Cookie。
• multimail-pp-cli operator create-startsession — 需要管理员权限范围。向监督邮箱发送一次性代码，并启动操作员会话 OTP 流程。
• multimail-pp-cli operator create-verifysession — 需要管理员权限范围。将一次性代码兑换为短时有效的 HttpOnly 操作员会话 Cookie。
• multimail-pp-cli operator list — 需要管理员权限范围。报告当前浏览器是否具有有效的操作员会话 Cookie。

oversight — 管理监督

• multimail-pp-cli oversight create — 需要监督权限范围。已批准的外发邮件会立即发送。
• multimail-pp-cli oversight list — 列出待监督审批的邮件

slug-check — 管理 slug 检查

• multimail-pp-cli slug-check <slug> — 检查 slug 是否可供注册。如果已被占用或保留，则返回建议。无需身份验证。

support — 管理支持

• multimail-pp-cli support — 公开端点。需要已通过验证的 ALTCHA 工作量证明载荷。向 [email protected] 发送消息。

suppression — 管理抑制

• multimail-pp-cli suppression delete — 允许再次向此地址发送邮件。需要管理员权限范围。
• multimail-pp-cli suppression list — 返回因退信、垃圾邮件投诉或手动取消订阅而被抑制的地址。需要管理员权限范围。

unsubscribe — 管理取消订阅

• multimail-pp-cli unsubscribe create — 处理取消订阅请求
• multimail-pp-cli unsubscribe get — 呈现取消订阅页面（CAN-SPAM）

usage — 管理用量

• multimail-pp-cli usage — 需要读取权限范围。返回当前计费周期的用量计数。

webhook-deliveries — 管理 webhook 投递

• multimail-pp-cli webhook-deliveries — 返回近期的 webhook 投递尝试。需要管理员权限范围。

webhooks — 管理 webhook

• multimail-pp-cli webhooks create — 订阅邮件事件。返回签名密钥（仅在创建时显示）。需要管理员权限范围。
• multimail-pp-cli webhooks create-postmark — Postmark 退信／投诉／投递 webhook 处理程序
• multimail-pp-cli webhooks create-postmarkinbound — 接收来自 Postmark 的入站邮件。通过 HTTP Basic Auth 使用 Postmark webhook 密钥进行身份验证。
• multimail-pp-cli webhooks delete — 删除 webhook 订阅
• multimail-pp-cli webhooks get — 包含签名密钥。需要管理员权限范围。
• multimail-pp-cli webhooks list — 需要管理员权限范围。列表中不包含签名密钥。

well-known — 管理 well-known

• multimail-pp-cli well-known get — 每个 IP 每小时最多查询 10 次。
• multimail-pp-cli well-known list — 返回用于签署 X-MultiMail-Identity 标头的 ECDSA P-256 公钥。
• multimail-pp-cli well-known list-wellknown — 返回 OAuth 授权服务器元数据，其中包含描述身份验证的 agent_auth 扩展块。
• multimail-pp-cli well-known list-wellknown-2 — 返回有关 MultiMail 作为受 OAuth 保护资源的元数据，包括支持的权限范围和授权服务器。

查找合适的命令

如果你知道要做什么，但不知道该用哪个命令，可以直接询问 CLI：

multimail-pp-cli which "<capability in your own words>"

which 会根据自然语言功能查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help，或使用更具体的查询。

操作示例

批准某个邮箱的所有待处理邮件

multimail-pp-cli oversight list --json --select id,subject,to | multimail-pp-cli oversight bulk-decide --approve --stdin

将待处理邮件 ID 传入批量批准命令，可用于清空受限邮箱的队列。

邮箱群组信任等级概览

multimail-pp-cli trust status --json --agent --select name,oversight_mode,time_at_level

查看各邮箱所处的信任等级，以及它们处于该等级的时长。

跨邮箱搜索并选择字段

multimail-pp-cli search 'quarterly report' --type emails --json --agent --select subject,from,mailbox,received_at

在所有已同步邮箱中查找特定邮件，并精简输出字段，以提高 Agent 上下文效率。

同步并检查收件箱状况

multimail-pp-cli sync --resources mailboxes,emails --since 24h && multimail-pp-cli inbox health --json

刷新本地数据，然后检查各邮箱的未读邮件数、回复率和最早未读邮件的存放时长。

允许列表覆盖率分析

multimail-pp-cli mailboxes allowlist coverage --mailbox primary --days 30 --json --agent --select pattern,match_count,percentage

查看近期收件人中符合允许列表模式的比例，并找出造成最多限制摩擦的地址。

身份验证设置

MultiMail 使用带前缀密钥的 Bearer 令牌身份验证：生产环境使用 mm_live_，预发布环境使用 mm_test_。请从 MultiMail 控制面板或通过 API 密钥管理端点获取密钥。

运行 multimail-pp-cli doctor 以验证设置。

Agent 模式

在任意命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

• 可管道传输 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对于控制上下文大小至关重要：

  multimail-pp-cli account list --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不会发送

• 支持离线 — 如果本地 SQLite 存储可用，同步／搜索命令可以使用它

• 非交互式 — 从不提示，每项输入都通过标志传入

• 显式重试 — 仅当已存在的创建应视为成功时才使用 --idempotent；仅当缺失的删除目标应视为成功时才使用 --ignore-missing

响应封装

从本地存储或 API 读取的命令会将输出封装在来源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 确认数据来自实时来源还是本地来源。只有当 stdout 是终端且未设置机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会将便于阅读的 N results (live) 摘要输出到 stderr；管道／Agent 使用者和指定格式的运行会在 stdout 上获得纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

multimail-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
multimail-pp-cli feedback --stdin < notes.txt
multimail-pp-cli feedback list --json --limit 10

条目会存储在本地的 ~/.local/share/multimail-pp-cli/feedback.jsonl。除非设置了 MULTIMAIL_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 MULTIMAIL_FEEDBACK_AUTO_SEND=true，否则永远不会通过 POST 发送。默认行为仅保存到本地。

写下让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是会不断积累的部分。

输出传递

每个命令都接受 --deliver <sink>。输出会发送到指定接收端，同时输出到 stdout，或替代 stdout 输出，因此 Agent 无需手动通过管道传递，即可路由命令结果。支持三种接收端：

接收端	效果
stdout	默认；仅写入 stdout
file:<path>	以原子方式将输出写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到 URL（使用 --compact 时为 application/json 或 application/x-ndjson）

不支持的方案会被拒绝，并返回列出受支持方案的结构化错误。Webhook 请求失败时会返回非零状态码，并在 stderr 上记录 URL 和 HTTP 状态码。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。当定时运行的 Agent 每次都以相同配置调用同一命令时，可使用配置——这是 HeyGen 的 “Beacon” 模式。

multimail-pp-cli profile save briefing --json
multimail-pp-cli --profile briefing account list
multimail-pp-cli profile list --json
multimail-pp-cli profile show briefing
multimail-pp-cli profile delete briefing --yes

显式标志的优先级始终高于配置值；配置值的优先级高于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便自省型 Agent 在运行时发现它们。

退出码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	触发速率限制（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 multimail-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参阅上文的先决条件
3. 其他任何内容 → 直接使用（作为带有 --agent 的 CLI 命令执行）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/multimail/cmd/multimail-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add multimail-pp-mcp -- multimail-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which multimail-pp-cli 如果未找到，请提供安装选项（参阅本技能顶部的先决条件）。
2. 根据上文的独特功能和命令参考，选择最匹配用户查询的命令。
3. 使用 --agent 标志执行：

   multimail-pp-cli <command> [subcommand] [args] --agent
   

4. 如果有歧义，请深入查看子命令帮助：multimail-pp-cli <command> --help。