用 Cargo 管理发件邮箱时如何开通、预热…

当需要通过 Cargo 拥有并运营发件邮箱（开通、预热、按日额度发送、读取线程/回复/事件、管理全局退订名单）时使用。

适用场景

解决思路

1. 先确认已登录：运行 `cargo-ai whoami` 返回工作区即跳过；否则 `npm install -g @cargo-ai/cli`（无全局安装则每条命令前加 `npx @cargo-ai/cli`），再 `cargo-ai login --email you@company.com`（邮件验证码，首次使用即创建账号），也可用 `--oauth`（浏览器）或 `--token <api-token>`（CI），写操作前用 `cargo-ai whoami` 确认当前工作区。
2. 注意所有命令输出 JSON 到 stdout，失败时非零退出并返回 `{"errorMessage": "..."}`；本域没有异步任务，无需轮询 run，唯一看似异步的新建邮箱 `pending` 状态用 `mailbox refresh-status` 轮询。
3. 权限：读取需 `mailboxManagement:read`，开通/更新/删除/抑制需 `mailboxManagement:write`；admin 和 editor 都有，viewer 没有，权限错误说明 token 只读。
4. 发送前必须执行三项阻塞式检查：1) Basis——确认覆盖该受众的许可（客户、已订阅联系人、活动参与者，或 B2B 角色的合法利益记录）；2) Suppression——在 enrich 或发送前先从受众中减去工作区抑制名单（`suppression list` 免费且是本域权威来源）；3) Relevance——能逐收件人说明为何这条消息是给他的。任一不通过就停下询问。
5. 把发送额度当作上限而非目标：`get-send-allowance` 报告的是当天可发量，不是要填满的配额；要求提高额度、把同一活动分散到一批新邮箱以清空同样体量、或轮换身份让过滤器少看到每个身份，都属于规避拒绝，不是配置问题。
6. 退订是自动且绝对的：每封发送都带签名的 `List-Unsubscribe` 头，收件人使用后会写入工作区级 `suppression` 行，下一次发送会被引擎拒绝；没有移除命令，也绝不要绕过抑制去重新联系。
7. 区分两个关键数字：`mailbox get-send-allowance` 衡量你自己的真实外联（滚动 24 小时，返回 `dailyLimit`、`sentCount`、`remainingCount`，回答“还能发多少”）；`mailbox get-warmup-stats` 衡量服务商的虚拟预热流量（当天 UTC，返回 `sentCount`、`deliveredCount`、`spamCount`、`inboxRate`、`spamRate`，回答“进收件箱还是垃圾箱”）。`dailyLimit` 不是设置项，而是由预热运行时长推导出来的。
8. 开通邮箱：`cargo-ai mailboxManagement mailbox create --domain-uuid <domain-uuid> --type google --username jane --first-name Jane --last-name Doe --signature '<p>Jane Doe · Acme</p>' --folder-uuid <folder-uuid>`，然后重复 `cargo-ai mailboxManagement mailbox refresh-status <uuid>` 直到状态为 `active`。
9. `--domain-uuid` 没有 CLI 命令可列出（`domainManagement` API 存在但无 CLI 界面）：从 Cargo Web 应用获取，或在 CDK 仓库用 `defineDomain` 声明后从 `cargo.state.json` 读取；不要猜 UUID。
10. `--type` 取 `google`、`shared` 或 `private`；`outlook` 虽被接受但总是失败并返回 `transportNotSupported`（Graph 传输未上线），不要选。
11. `--username` 只填本地部分（`jane@acme.com` 填 `jane`），会转小写，允许字母、数字、点、横线、下划线，1–64 字符，首尾为字母数字。
12. `--first-name` / `--last-name` 是收件人看到的 From 头，必须用真实身份下的真实人名；伪造发件人属于拒绝项。
13. `--signature` 为 HTML，存在邮箱上（最多 10,000 字符）；`--folder-uuid` 是 kind 为 `mailbox` 的文件夹。
14. `create` 立即返回 `status: "pending"`（服务商尚未发放凭据），在 `refresh-status` 确认或最多五分钟后变为 `active`；在此之前发送会失败并返回 `credentialsMissing`。
15. 列出与查看：`cargo-ai mailboxManagement mailbox list`（全部）、`mailbox list --statuses active`（逗号分隔、无空格）、`mailbox list --domain-uuid <uuid>`、`mailbox get <uuid>`。
16. 更新：`cargo-ai mailboxManagement mailbox update --uuid <uuid> --first-name Janet`；`--folder-uuid none` 表示清除（`--signature` 同理）；`list` 上 `--folder-uuid none` 表示“不在任何文件夹中的邮箱”。
17. 删除：`cargo-ai mailboxManagement mailbox remove <uuid>`（同时删除服务商侧），这是停止月度计费的唯一方式，没有暂停。
18. `--statuses` 取 `pending`、`active`、`inactive`，逗号分隔且无空格；`inactive` 是被服务商禁用，`errorCode` 说明原因（`401` 认证、`402` 垃圾邮件），修复前不会发送。
19. 预热：`cargo-ai mailboxManagement mailbox start-warmup <uuid> --daily-target 40`；`--daily-target` 是满负荷时每天的预热消息数，1–40（默认 40），是服务商虚拟流量而非你的发送额度。
20. 查看预热统计：`cargo-ai mailboxManagement mailbox get-warmup-stats <uuid>`（需较新 CLI；旧版会静默打印 `mailbox` 组帮助而非报错）。
21. 调整预热：`cargo-ai mailboxManagement mailbox update-warmup --uuid <uuid> --status paused` 或 `--daily-target 25`；`--status` 接受整个枚举但只有 `active` 和 `paused` 有效，`pending`/`failed` 由服务商自行到达，`disabled` 是 `stop-warmup` 的用途。
22. `stop-warmup` 会同时重置 Cargo 发送爬坡（邮箱跌回 5/天并重新开始 45 天），除非确定否则用暂停。
23. 发送前检查额度：`cargo-ai mailboxManagement mailbox get-send-allowance <uuid>`，在把一批人加入前先读 `remainingCount`；超出额度的发送不会排队到明天，而是立即失败并返回 `dailyLimitReached`，每行浪费一次运行。
24. 读取消息/线程/事件：`cargo-ai mailboxManagement message list --mailbox-uuid <uuid> --statuses sent,replied --limit 50`、`message get <uuid>`、`thread list --mailbox-uuid <uuid> --search acme`、`thread get <uuid>`、`event list --kinds replied,unsubscribed --occurred-after 2026-08-01`。
25. 区分三者：message 是一次外发发送；thread 是一段对话（其 `lastEmail` 和 `lastEvent` 是回复队列排序依据）；event 是消息上发生的事（`sent`、`opened`、`clicked`、`replied`、`bounced`、`unsubscribed`）。入站回复是事件而非 message 行，只有外发邮件才是 message。
26. `message list` / `thread list` 的 `--statuses` 是列表状态（`pending`、`error` 或某个事件 kind），不含 `success`；已送达的消息读作 `sent` 或更晚。`--kinds`、`--statuses`、`--reasons` 均为逗号分隔无空格。
27. `bounced` 目前永不触发：没有解析投递状态通知，退信不产生事件也不自动抑制；不要把空的退信计数当作干净名单。
28. `message`、`thread`、`event` 列表默认 `--limit 50`（最大 200）并返回 `count`；`mailbox list` 和 `suppression list` 没有默认限制（最大 1000），且 `mailbox list` 不返回 `count`。
29. 抑制名单是工作区级而非按邮箱：`cargo-ai mailboxManagement suppression list --reasons unsubscribed,manual`、`cargo-ai mailboxManagement suppression create --email opted-out@acme.com`。
30. 抑制原因有 `unsubscribed`（收件人通过 `List-Unsubscribe` 自行选择）、`bounced`、`complained`、`manual`；`suppression create` 总是记录 `manual`。
31. 抑制是幂等的（重复抑制已抑制地址返回现有行）；地址在写入和检查时都会规范化（`trim().toLowerCase()`），大小写和空白无法让被抑制收件人溜回发送；没有 `suppression remove`，这是刻意的。
32. 定价：`cargo-ai mailboxManagement pricing get` 返回 `{"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}`；报价前实时读取，不要当作常量。
33. 发送通过编排动作而非本 CLI 域：`cargo-ai orchestration action execute --action '{"kind":"native","actionSlug":"sendEmail"}' --data '{"mailboxUuid":"<mailbox-uuid>","to":"jane@acme.com","subject":"...","bodyHtml":"<p>…</p>"}' --wait-until-finished`。
34. `sendEmail` 每次发送固定 0.1 credits；动作不带 `config`，输入放在 `--data`；可选 `bodyText`（省略时由 HTML 生成）、`inReplyTo`、`references`。
35. 保持回复线程：`references` 要包含该线程至今所有 `Message-ID`，从旧到新，而不只是父消息，否则邮件客户端会断线程。
36. 动作按邮箱限速到该邮箱自己的日限额并分散在全天；在还剩 40 的邮箱上突发 100 封，第 41 封立即失败而不是推迟一天。
37. 被拒绝的发送是节点错误而非抛异常：`recipientSuppressed`、`mailboxNotActive`、`transportNotSupported` 需要人工且不重试；`dailyLimitReached`、`credentialsMissing`、`deliveryFailed` 会自行重试。
38. CLI 没有 dry run（引擎有但无 `action execute` 标志可达），命令一运行就是真实发送；先发给自己测试。
39. 在工作流内读取事件用原生动作 `listEmailEvents`（CLI ≥ 1.0.86）：`cargo-ai orchestration action execute --action '{"kind":"native","actionSlug":"listEmailEvents"}' --data '{"threadUuid":"<thread-uuid>","kinds":["replied","clicked"],"limit":50}' --wait-until-finished`；`threadUuid` 必填，`kinds` 可选（省略为全部），`limit` 默认 50、上限 200、最新在前。
40. 事件 kind 为 `sent`、`opened`、`clicked`、`replied`、`bounced`、`unsubscribed`；注意线上值是 `opened`，尽管 UI 标为 "Viewed"。每个事件返回 `uuid`、`mailboxUuid`、`messageUuid`、`threadUuid`、`kind`、`occurredAt`、`actorEmail`，以及可空的 `url`（`clicked` 时）、`inboundRfcMessageId`、`snippet`。
41. 成本纪律：邮箱是每月经常性费用（每个邮箱每月 100–160 credits，只要存在就一直计费），五个邮箱就是每月 500–625 credits 而非一次性；`mailbox remove` 是唯一停止方式，没有暂停；首次 `create` 前用实时 `pricing get` 报出机队规模和月度 credit 估算并取得明确同意。
42. 发送每封 0.1，所以量便宜而机队不便宜，按这个顺序算账；调用 `sendEmail` 的 play 或定时工具每次运行都会重新计费并重新联系同一批人（既是花费门槛也是节奏门槛）；把一批人加入前先查 `get-send-allowance`，超出额度的行每次运行都白烧且不投递。
43. 邮箱本身优先用 CDK 声明式：`defineMailbox`（配合 `defineDomain` 声明发件域），`adopt: true` 可绑定 Web 应用里已购买的邮箱而不是再开一个；本技能的命令式命令用于一次性开通，以及 CDK 完全不建模的部分：预热、额度、消息、线程、事件、抑制。
44. 当 CLI 行为与文档不符时，重新刷新 CLI 和 skills；仍不对就提交报告：`cargo-ai workspaceManagement report create --title "<one-line summary>" --description "<exact command(s), errorMessage verbatim, expected vs actual, UUIDs>"`。
45. 呈现结果时先给结论（如“邮箱已激活，今天 12 封还剩 8 封，周一以来 2 条回复”），机队或回复队列用紧凑表格汇总，绝不把原始 `mailbox get` 或 `event list` JSON 倒进对话；报告机队时报告其月度成本而非一次性成本。

适用边界 · 注意事项

• 撰写文案或构建受众时不要用本技能，改用 cargo-gtm。
• 邮箱应纳入 git 管理时不要用本技能的命令式开通，改用 cargo-project 的 CDK 声明式方式。
• 不要用本技能做实际投递发送——发送是 `sendEmail` 编排动作，属于 cargo-orchestration。