cargo-mailbox-management

Cargo CLI — 邮箱管理

邮箱。 邮箱是工作区拥有的真实发件收件箱——由 Cargo 在工作区同样拥有的发送域上配置，Cargo 持有 SMTP 和 IMAP 凭据，并用它们发送外发邮件、读取收到的回复。由此有两点需要注意，而且很容易搞错：邮箱是每月定期扣除额度，而非按记录扣除；此外，此域不负责发送。它负责配置收件箱、逐步提升发送量并报告发送情况；真正发送邮件的是 sendEmail 操作，位于 cargo-orchestration。

cargo-ai mailboxManagement mailbox      …   # provision, warm-up, send allowance
cargo-ai mailboxManagement message      …   # outbound sends
cargo-ai mailboxManagement thread       …   # conversations, and the replies on them
cargo-ai mailboxManagement event        …   # sent / opened / clicked / replied / unsubscribed
cargo-ai mailboxManagement suppression  …   # workspace-wide do-not-send list
cargo-ai mailboxManagement pricing      …   # monthly credits per mailbox flavour

版本说明。 本页所述功能均已在固定版本的 CLI（1.0.66）中上线，包括 mailbox get-warmup-stats 和默认值为 40 的 --daily-target——编写此技能时，这两项功能都已合并，但尚未发布。在较旧版本的 CLI 中，--daily-target 显示为“省略时使用提供方默认值”，而 get-warmup-stats 会静默打印 mailbox 组的帮助信息，而不会报错，因此这里缺少子命令时看起来像是用法错误，而不是安装版本过旧。运行 cargo-ai mailboxManagement mailbox --help 查看你的 CLI 实际支持的命令；重新执行 ../cargo/SKILL.md 中的会话刷新步骤以获取更新。

初始化

如果已经登录（cargo-ai whoami 返回工作区），请跳至下一节。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

每条命令都会将 JSON 输出到 stdout；失败时以非零状态码退出，并返回 {"errorMessage": "..."}。 此域中的操作均为同步操作——每条命令只发起一次 HTTP 调用，因此无需轮询运行状态（唯一看起来像是异步的情况，是新建邮箱暂处于 pending 状态；应使用 mailbox refresh-status 轮询，而不是使用 run get）。邮箱受 mailboxManagement:read / mailboxManagement:write 权限保护，管理员和编辑者拥有这些权限，查看者则没有；如果创建或更新操作返回权限错误，说明令牌为只读（../cargo-workspace-management/SKILL.md）。安装完整技能包后，../cargo/references/prerequisites.md 还会补充 CLI 版本固定要求、令牌作用域以及仅限管理员使用的功能。

发送前的三项检查

这是必须通过的关卡，不是建议。 Cargo 拥有邮箱改变的是由谁按下发送键；它不会改变邮件是否应该发送。规范规则见 ../cargo-gtm/references/acceptable-use.md §3，此处同样适用——首次执行 sendEmail 之前必须完成以下三项检查，而不是发送之后：

• 依据——哪些许可适用于此受众（客户、已主动同意接收信息的联系人、活动参与者，或有记录的 B2B 职位合法利益案例）？
• 抑制名单——在补充受众信息或发送之前，从受众中排除工作区抑制名单。suppression list 免费，此域是该名单的权威来源。
• 相关性——你能否针对每位收件人说明这封邮件为何与其相关？

任何一项检查未通过，都必须停止并询问。Cargo 自有发送邮箱还涉及两项特定义务：

• 预热量是上限，不是目标。 get-send-allowance 会报告邮箱今天最多可以发送的邮件数；这不是必须用满的配额。要求提高上限、将同一营销活动分摊到一批新邮箱以完成相同发送量，或轮换身份以减少过滤器看到的每个身份的发送量，都属于 acceptable-use.md §2 中禁止的规避行为，而非配置问题。
• 退订会自动执行，且不可撤销。 每次发送都会附带已签名的 List-Unsubscribe

标头；收件人使用该标头退订后，会在整个工作区写入一条 suppression 记录，随后引擎会拒绝向该地址发送邮件。没有删除命令，这正是设计目的——绝不能绕过抑制名单再次联系某人。

控制邮箱的两个数字

它们看起来相似，含义却恰好相反。混淆二者是误读邮箱健康状况的最常见原因。

	mailbox get-send-allowance	mailbox get-warmup-stats
衡量内容	你的实际外联邮件	服务提供商的模拟预热流量
时间范围	滚动 24 小时	今日，UTC
返回内容	dailyLimit、rampLimit、sentCount、remainingCount	sentCount、deliveredCount、spamCount、inboxRate、spamRate
回答的问题	“我还能再发多少封？”	“这些邮件是进入收件箱还是垃圾邮件？”

dailyLimit 不是一项设置，而是根据预热持续时间推算得出的。相关计算、warmupStatus 状态转换，以及如何据此规划邮箱集群容量，请参阅**references/warmup-and-allowance.md**。向任何人承诺发送量之前，请先阅读。

命令

所有命令都输出 JSON。读取操作需要 mailboxManagement:read 权限；任何配置、更新、删除或抑制操作都需要 mailboxManagement:write 权限。

配置邮箱

首先，你会遇到这个缺口。 mailbox create 需要 --domain-uuid，而 cargo-ai 没有列出发送域名的命令——domainManagement API 已存在，但尚未提供 CLI 接口。请从 Cargo Web 应用获取 UUID，或使用 defineDomain 在项目中声明域名，然后从 cargo.state.json 中读取。请将此情况告知用户，不要猜测 UUID。

购买域名之前为其定价也存在同样的缺口，只需进行一次直接 API 调用即可解决：GET /v1/domainManagement/domains/search?name=<domain> 会返回 available 和 priceCredits（其中 null 表示不可购买，而非免费）。发送域名在邮箱集群中的作用——该调用、根据影响范围而非容量确定域名数量、根域名重定向、DMARC、命名，以及声明域名后由 dnsRecords 管理的内容——请参阅**references/sending-domains.md**。

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>   # repeat until status is "active"

• --type — google、shared 或 private。outlook 虽然可作为此标志的值，但始终会失败，并返回 transportNotSupported：Graph 传输尚未发布，因此 Outlook 邮箱无法发送邮件。请选择其他三种类型之一。
• --username — 仅填写本地部分（例如 [email protected] 中的 jane）。会转换为小写；可使用字母、数字、点、短横线和下划线，长度为 1–64 个字符，且首尾必须为字母或数字。
• --first-name / --last-name — 收件人看到的发件人名称。请在真实身份下使用真实姓名；虚构发件人属于 §2 所述的拒绝情形。
• --signature — HTML，存储在邮箱中（最多 10,000 个字符）。
• --folder-uuid — 来自 cargo-workspace-management 的 mailbox 类型文件夹。

create 会立即返回 status: "pending"——服务提供商尚未发放凭据。refresh-status 显示状态后，邮箱会变为 active；如果未调用该命令，则最多五分钟后自动变为 active。在此之前尝试发送会失败，并返回 mailboxNotActive，且不会重试。

cargo-ai mailboxManagement mailbox list                        # every mailbox
cargo-ai mailboxManagement mailbox list --statuses active      # comma-separated, no spaces
cargo-ai mailboxManagement mailbox list --domain-uuid <uuid>
cargo-ai mailboxManagement mailbox get <uuid>

cargo-ai mailboxManagement mailbox update --uuid <uuid> --first-name Janet
cargo-ai mailboxManagement mailbox update --uuid <uuid> --folder-uuid none   # "none" clears

cargo-ai mailboxManagement mailbox remove <uuid>               # deletes at the provider too

• --statuses — pending、active、inactive、error，以逗号分隔，不加空格。inactive 邮箱表示已被服务提供商停用；errorCode 会说明原因（401 表示身份验证，402 表示垃圾邮件问题），修复之前无法发送邮件。error 邮箱表示 Cargo 无法登录，但服务提供商仍将其视为活跃状态（errorCode: "authenticationFailed"）；系统每小时重试一次，并会在首次成功登录后恢复为 active。
• none 是 --folder-uuid 和 --signature 的“清除”哨兵值。在 list 命令中，--folder-uuid none 表示“未归入任何文件夹的邮箱”。
• remove 用于停止按月计费。没有暂停选项。

预热

从未启动预热的邮箱会永远被限制为每天实际发送 5 封。预热可以逐步提高这个上限，完成需要 45 天。邮箱首次从 pending 变为 active 时会自动启动预热（目标为 40）；start-warmup 用于在注册失败或执行 stop-warmup 后重试，而对于已在预热的邮箱，它会返回 warmupAlreadyStarted。

cargo-ai mailboxManagement mailbox start-warmup <uuid> --daily-target 40
cargo-ai mailboxManagement mailbox get-warmup-stats <uuid>

cargo-ai mailboxManagement mailbox update-warmup --uuid <uuid> --status paused
cargo-ai mailboxManagement mailbox update-warmup --uuid <uuid> --daily-target 25
cargo-ai mailboxManagement mailbox stop-warmup <uuid>                         # resets the ramp

• --daily-target — 达到完整爬坡阶段时每天发送的预热消息数，范围为 1–40（默认值为 40）。这是服务提供商的虚拟流量，不是你的发送额度。
• update-warmup 的 --status 接受完整枚举，但只有 active 和 paused 会生效：pending 和 failed 是服务提供商自行设置的状态，而 disabled 则是 stop-warmup 的用途。
• stop-warmup 会重置 Cargo 的发送爬坡进度，并拆除服务提供商的预热；邮箱会降回每天 5 封，并重新开始 45 天的爬坡。除非你确实想重置，否则请改用暂停。

发送前检查额度

cargo-ai mailboxManagement mailbox get-send-allowance <uuid>
# → {"allowance":{"dailyLimit":12,"rampLimit":12,"sentCount":4,"remainingCount":8}}

批量发送前先读取 remainingCount。超出该值的发送不会失败：它们会等待滚动 24 小时窗口腾出名额，因此积压会在接下来的几天内逐步清空。一次工作流运行最长约 15 天，所以如果积压超过约 15 天的发送额度（预热完成的邮箱约为 600 封），等待清空的时间会超过本次运行时长。rampLimit 表示爬坡阶段的额度；dailySendLimit 覆盖值可能会进一步收紧该额度。

查看发生了什么

cargo-ai mailboxManagement message list --mailbox-uuid <uuid> --statuses sent,replied --limit 50
cargo-ai mailboxManagement message get <uuid>

cargo-ai mailboxManagement thread list --mailbox-uuid <uuid> --search acme
cargo-ai mailboxManagement thread get <uuid>

cargo-ai mailboxManagement event list --kinds replied,unsubscribed --occurred-after 2026-08-01

• 消息、对话线程和事件。 一条消息是一次外发。一条对话线程是一段对话——排序回复队列时，要依据它的 lastEmail 和 lastEvent。事件是消息发生的情况（sent、opened、clicked、replied、bounced、unsubscribed）。入站回复是事件，不是消息行；只有外发邮件才是消息。
• message list / thread list 的 --statuses 是列表状态，可选 pending、error 或某种事件类型。success 不属于该集合：已送达的消息会显示为 sent 或后续状态。
• --kinds、--statuses 和 --reasons 的值均以逗号分隔，且不能包含空格。
• bounced 目前不会触发。 系统不会解析投递状态通知，因此退信不会生成事件，也不会自动抑制。不要构建把退信数为空视为列表无异常的投递能力报告。
• message、thread 和 event 列表默认使用 --limit 50（上限为 200），并返回 count。mailbox list 和 suppression list 没有默认限制（上限为 1000），而 mailbox list 不会返回 count——请参阅 references/response-shapes.md。

抑制

抑制范围是整个工作区，而非单个邮箱：收件人选择退订，表示退订发件人，而不是发件人恰好拥有的某个地址。

cargo-ai mailboxManagement suppression list --reasons unsubscribed,manual
cargo-ai mailboxManagement suppression create --email [email protected]

• 原因包括 unsubscribed（收件人通过 List-Unsubscribe 自行选择）、bounced、complained 和 manual。suppression create 始终记录为 manual。
• 操作具有幂等性——抑制已被抑制的地址时，会返回现有记录。
• 写入和检查时都会规范化地址（trim().toLowerCase()），因此大小写差异和多余空格都无法让已抑制的收件人重新进入发送流程。
• 没有 suppression remove。这是有意为之。

定价

cargo-ai mailboxManagement pricing get
# → {"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}

引用整个邮箱群组的费用前，请读取此处的实时数据——上面的数字是本文编写时工作区返回的结果，并非固定值。

发送：sendEmail 操作

投递功能有意不归入此 CLI 领域。它是原生编排操作，因此发送会沿用编排的节奏控制、重试和额度机制：

cargo-ai orchestration action execute \
  --action '{"kind":"native","actionSlug":"sendEmail"}' \
  --data '{"mailboxUuid":"<mailbox-uuid>","to":"[email protected]","subject":"...","bodyHtml":"<p>…</p>"}' \
  --wait-until-finished

• 每次发送固定消耗 0.1 个额度。 此操作不携带 config；输入放在 --data 中，与其他所有操作一样（../cargo-orchestration/SKILL.md）。
• 可选的 bodyText（省略时由 HTML 生成）、inReplyTo 和 references。
• 要让回复保持在同一会话线程中，必须发送完整的链。 references 应包含该线程目前为止的每个 Message-ID，按时间从早到晚排列，而不只是父消息。否则邮件客户端会拆分线程。
• 发送速率限制按邮箱单独计算：上限为该邮箱自身的每日限额，两次发送之间随机间隔 1 到 3 分钟。某邮箱剩余额度为 40 时，批量发送 100 封会先发送 40 封，其余 60 封会等到限额窗口刷新，而不会失败。
• 被拒绝的发送会产生节点错误，而不是抛出异常。 recipientSuppressed、mailboxNotActive、mailboxSendingPaused、mailboxNotFound 和 transportNotSupported 需要人工处理，不会重试；dailyLimitReached、credentialsMissing 和 deliveryFailed 会自动重试。
• CLI 不支持试运行。 引擎支持试运行，但没有 action execute 标志能传递给它——运行命令后，发送会立即生效。先发给自己。

关于线程处理、完整的拒绝原因表，以及 Cargo 注入每封邮件的内容（退订标头、打开追踪像素、点击重定向），请参阅 references/sending.md。

从工作流中读取事件：listEmailEvents

mailboxManagement event list 是 CLI 中的读取方式；而在工作流中，线程上的投递事件来自原生操作（CLI ≥ 1.0.86），因此 play 可以根据是否有人回复来分支处理：

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，按时间从新到旧排列。
• 事件类型包括 sent、opened、clicked、replied、bounced、unsubscribed。请注意，传输值为 opened，即使 UI 上显示为“已查看”。
• 每个事件都会返回 uuid、mailboxUuid、messageUuid、threadUuid、kind、occurredAt、actorEmail，以及可为空的 url（适用于 clicked）、inboundRfcMessageId 和 snippet。
• bounced 目前仍没有数据来源——尚无任何组件解析投递状态通知，因此按此类型筛选不会返回任何结果，也不能证明任何情况。切勿把退信计数为零报告为名单干净。

成本控制

此领域的计费方式与此套件中的其他部分不同；在配置任何内容前，必须明确说明这种差异。

• 邮箱按月重复收费——每个邮箱每月消耗 100–160 个额度，只要邮箱存在就会持续收费。五个邮箱每月消耗 500–625 个额度，而不是一次性消耗。只有 mailbox remove 能停止收费；没有暂停选项。请根据实时 pricing get 报出邮箱总数和每月额度估算，并在首次执行 create 前取得明确同意。
• 每次发送消耗 0.1 个额度，因此发送量成本低，邮箱组成本高。请按此顺序计算。
• 每次运行调用 sendEmail 的 play 或计划任务都会重新计费，并且每次运行都会再次联系相同的人；这同样涉及 acceptable-use.md 第 6 节的频率限制，而不仅是成本限制。在将一批联系人加入任务前，请检查 get-send-allowance：超出限额的行会等待后续窗口处理，积压量若超过约 15 天的限额，则会超过该任务的运行周期。
• 完整的支出规则——包括全面加入前的抽样、审批消息和收据——见 ../cargo-gtm/references/cost-discipline.md。

声明式替代方案：defineMailbox（项目）

对于收件箱本身，优先使用项目——mailbox create 的帮助信息也如此建议，原因在于邮箱是长期运行且需要按月付费的基础设施，正适合纳入 Git 和可供审核的计划中。defineMailbox（发送域名则使用 defineDomain）即可覆盖此场景；adopt: true 可以关联在 Web 应用中购买的邮箱，而不是再创建一个。请参阅 ../cargo-project/SKILL.md 以及 ../cargo/SKILL.md 中的“声明式与命令式”。

对于一次性配置，以及项目完全无法建模的所有内容，请使用本技能的命令式命令：预热、配额、邮件、邮件线程、事件和抑制项。

CLI 出现意外情况时

如果文档中说明的标志或响应格式与实际观察到的不符，请重新刷新 CLI 和技能；如果仍然对不上，请提交报告——团队会查看。缺失的 domainManagement 接口就是一个实际案例：mailbox create 需要一个 --domain-uuid，但没有任何命令能生成它。

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<exact command(s), errorMessage verbatim, expected vs actual, UUIDs>"

呈现结果

请遵循 ../cargo/references/interaction.md：先说明结果（“邮箱已激活，今天 12 封邮件还可发送 8 封，自周一以来收到 2 封回复”），将邮箱群组或待回复队列汇总为简洁的表格，绝不要把原始的 mailbox get 或 event list JSON 直接贴到对话中。报告邮箱群组时，请报告其月度费用，而非一次性费用。