cargo-mailbox-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CLI — Mailbox Management

Cargo CLI — 邮箱管理

Mailboxes. A mailbox is a real sending inbox the workspace owns — provisioned through Cargo on a sending domain the workspace also owns, with SMTP and IMAP credentials Cargo holds and uses to deliver outbound mail and to read the replies that come back. Two things follow, and both are easy to get wrong: a mailbox is a recurring monthly credit charge rather than a per-record one, and this domain does not send. It provisions the inbox, ramps it, and reports on what it did; the send itself is the

sendEmail

action, under

cargo-orchestration

bash

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

Version note.
mailbox get-warmup-stats
and the documented
--daily-target
default of 40 are merged but not yet on npm. On an older CLI,
--daily-target
reads "provider default if omitted", and
get-warmup-stats
silently prints the
mailbox
group help instead of erroring — so an unrecognised subcommand here looks like a usage mistake, not a missing feature.
cargo-ai mailboxManagement mailbox --help
lists what your CLI actually has. Everything else on this page is live in the released CLI; re-run the session refresh in
../cargo/SKILL.md
to pick up the rest.

邮箱（Mailbox）。邮箱是工作区自有的真实发送收件箱——通过Cargo在工作区同样拥有的发送域名上配置，Cargo持有SMTP和IMAP凭据，用于发送出站邮件并读取回复。有两点需要注意，且很容易出错：邮箱是月度 recurring credit 收费项，而非按记录收费；该域名并不直接发送邮件，它负责配置收件箱、执行暖箱流程并报告操作结果；实际发送由

sendEmail

动作完成，相关内容见

cargo-orchestration

。

bash

cargo-ai mailboxManagement mailbox      …   # 配置、暖箱、发送额度管理
cargo-ai mailboxManagement message      …   # 出站邮件发送
cargo-ai mailboxManagement thread       …   # 对话及回复
cargo-ai mailboxManagement event        …   # 已发送/已打开/已点击/已回复/已退订事件
cargo-ai mailboxManagement suppression  …   # 工作区全局禁发列表
cargo-ai mailboxManagement pricing      …   # 不同类型邮箱的月度credits费用

版本说明。
mailbox get-warmup-stats
命令及文档中默认的
--daily-target
值40已合并代码，但尚未发布到npm。在旧版本CLI中，若省略
--daily-target
，会显示「使用服务商默认值」；而
get-warmup-stats
命令会静默打印
mailbox
组的帮助信息，而非报错——因此无法识别的子命令看起来像是使用错误，而非缺失功能。可通过
cargo-ai mailboxManagement mailbox --help
查看当前CLI实际支持的命令。本文档中的其他内容均已在已发布的CLI中生效；如需获取最新功能，请重新执行
../cargo/SKILL.md
中的会话刷新操作。

Bootstrap

初始化

Already signed in (

cargo-ai whoami

returns a workspace)? Skip to the next section.

bash

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # 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

Every command prints JSON to stdout; failures exit non-zero with

{"errorMessage": "..."}

. Nothing in this domain is asynchronous — every command is a single HTTP call, so there is no run to poll (the one thing that looks async, a freshly created mailbox sitting at

pending

, is polled with

mailbox refresh-status

, not with

run get

). Mailboxes are guarded by

mailboxManagement:read

mailboxManagement:write

permissions, which an admin and an editor both hold and a viewer does not; if a create or update returns a permission error, the token is read-only (

../cargo-workspace-management/SKILL.md

). When the full skill bundle is installed,

../cargo/references/prerequisites.md

adds the CLI version pin, token scopes, and the admin-only surface.

已登录（

cargo-ai whoami

可返回工作区信息）？请跳过本节直接查看下一部分。

bash

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                         # 执行任何写入操作前，确认当前激活的工作区

所有命令都会向stdout输出JSON；执行失败时会返回非零退出码及

{"errorMessage": "..."}

。本模块中所有操作均为同步——每个命令对应一次HTTP调用，因此无需轮询运行状态（唯一看似异步的操作是新创建的邮箱处于

pending

状态，需通过

mailbox refresh-status

轮询，而非

run get

）。邮箱受

mailboxManagement:read

mailboxManagement:write

权限保护，管理员和编辑拥有该权限，查看者则没有；若创建或更新操作返回权限错误，说明当前令牌为只读权限（详见

../cargo-workspace-management/SKILL.md

）。安装完整技能包后，

../cargo/references/prerequisites.md

会添加CLI版本固定、令牌权限范围及管理员专属功能说明。

Before any send — three checks

发送前的三项检查

This is a blocking gate, not advice. Cargo owning the mailbox changes who presses send; it changes nothing about whether the message should be sent. The canonical rules are

../cargo-gtm/references/acceptable-use.md

§3 and they apply here unchanged — run all three before the first

sendEmail

, not after:

Basis — which permission covers this audience (customers, opted-in contacts, event attendees, or a documented legitimate-interest case for a B2B role)?
Suppression — subtract the workspace suppression list from the audience before you enrich or send.
```
suppression list
```
is free and this domain is the source of truth for it.
Relevance — can you name, per recipient, why this message is for them?

Any check that fails is a stop-and-ask. Two obligations are specific to Cargo-owned sending:

The ramp is a ceiling, not a target.
```
get-send-allowance
```
reports what a mailbox may send today; it is not a quota to fill. Asking to raise it, to spread one campaign across a fleet of fresh mailboxes to clear the same volume, or to rotate identities so filters see less from each, is the evasion refusal in
```
acceptable-use.md
```
§2 — not a configuration question.
Unsubscribes are automatic and absolute. Every send carries a signed
```
List-Unsubscribe
```
header; a recipient using it writes a workspace-wide
```
suppression
```
row, and the next send to that address is refused by the engine. There is no removal command, and that is the point — never route around a suppression to re-contact someone.

这是强制校验，而非建议。Cargo拥有邮箱所有权改变了发送主体，但并未改变是否应该发送邮件的规则。标准规则见

../cargo-gtm/references/acceptable-use.md

第3节，此处完全适用——请在首次执行

sendEmail

前完成全部三项检查，而非事后补做：

合规性——针对该受众群体，您拥有何种发送权限（客户、已选择加入的联系人、活动参与者，或B2B场景下有文档记录的合法利益案例）？
退订校验——在进行受众群体扩充或发送前，需从受众中排除工作区退订列表中的用户。
```
suppression list
```
命令免费使用，且本模块是退订列表的唯一可信来源。
相关性——您能否针对每个收件人说明该邮件与他们相关的原因？

任何一项检查不通过都需停止操作并确认。针对Cargo自有发送邮箱，还有两项特定义务：

暖箱上限并非目标值。
```
get-send-allowance
```
命令会报告邮箱今日可发送的最大数量；这并非必须用尽的配额。请求提高上限、将一个活动分散到多个新邮箱以发送相同数量的邮件，或轮换身份以降低每个邮箱的发送频率，均属于
```
acceptable-use.md
```
第2节中禁止的规避行为——而非配置问题。
退订操作自动且不可撤销。每一封发送的邮件都会携带签名的
```
List-Unsubscribe
```
头部；收件人点击退订后，会在工作区全局
```
suppression
```
列表中添加记录，下次向该地址发送邮件时会被引擎拒绝。没有移除退订记录的命令，这是刻意设计的——永远不要绕过退订列表重新联系用户。

The two numbers that govern a mailbox

控制邮箱的两个关键指标

They look similar and mean opposite things. Confusing them is the most common way to mis-read a mailbox's health.

	`mailbox get-send-allowance`	`mailbox get-warmup-stats`
Measures	Your real outreach	The provider's dummy warm-up traffic
Window	Rolling 24 hours	Today, UTC
Returns	`dailyLimit` , `sentCount` , `remainingCount`	`sentCount` , `deliveredCount` , `spamCount` , `inboxRate` , `spamRate`
Answers	"How many more may I send?"	"Is this inbox landing in the inbox or in spam?"

dailyLimit

is not a setting — it is derived from how long warm-up has been running. The arithmetic, the

warmupStatus

transitions, and how to size a fleet against it are in references/warmup-and-allowance.md
. Read it before you promise anyone a send volume.

它们看起来相似，但含义完全相反。混淆这两个指标是误判邮箱健康状态最常见的原因。

	`mailbox get-send-allowance`	`mailbox get-warmup-stats`
衡量内容	您的实际触达量	服务商的模拟暖箱流量
统计周期	滚动24小时	当日（UTC时区）
返回字段	`dailyLimit` , `sentCount` , `remainingCount`	`sentCount` , `deliveredCount` , `spamCount` , `inboxRate` , `spamRate`
解答问题	"我今天还能发送多少邮件？"	"此邮箱的邮件是进入收件箱还是垃圾邮件？"

dailyLimit

并非可设置的参数——它由暖箱运行时长推导而来。具体计算方式、

warmupStatus

状态转换规则，以及如何根据该指标规划邮箱集群规模，请查看**

references/warmup-and-allowance.md

**。在向他人承诺发送量之前，请务必阅读该文档。

Commands

命令说明

All commands output JSON. Reads need

mailboxManagement:read

; everything that provisions, updates, deletes, or suppresses needs

mailboxManagement:write

所有命令均输出JSON格式结果。读取操作需要

mailboxManagement:read

权限；所有配置、更新、删除或屏蔽操作需要

mailboxManagement:write

权限。

Provision a mailbox

配置邮箱

First, the gap you will hit.

mailbox create

requires

--domain-uuid

, and there is no

cargo-ai

command that lists sending domains — the

domainManagement

API exists but has no CLI surface yet. Get the UUID from the Cargo web app, or declare the domain in a CDK repo with

defineDomain

and read it back from

cargo.state.json

. Say this to the user rather than guessing a UUID.

bash

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
```
, or
```
private
```
. outlook
is accepted by the flag and always fails with
```
transportNotSupported
```
: the Graph transport has not shipped, so an Outlook mailbox cannot deliver. Pick one of the other three.
```
--username
```
— the local part only (
```
jane
```
for
```
jane@acme.com
```
). Lowercased; letters, digits, dots, dashes and underscores, 1–64 characters, starting and ending alphanumeric.
```
--first-name
```
/
```
--last-name
```
— the From header the recipient sees. Use a real person's name under a real identity; a fabricated sender is a §2 refusal.
```
--signature
```
— HTML, stored on the mailbox (max 10,000 characters).

--folder-uuid

— a folder of kind

mailbox

, from

cargo-workspace-management

create

returns immediately with

status: "pending"

— the provider has not issued credentials yet. It reaches

active

when

refresh-status

says so, or on its own within five minutes; a send attempted before then fails with

credentialsMissing

bash

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
```
, comma-separated with no spaces. An
```
inactive
```
mailbox was disabled by the provider;
```
errorCode
```
says why (
```
401
```
auth,
```
402
```
spam) and it will not send until it is fixed.
```
none
```
is the sentinel for "clear it" on
```
--folder-uuid
```
and
```
--signature
```
. On
```
list
```
,
```
--folder-uuid none
```
means "mailboxes in no folder".
```
remove
```
is how monthly billing stops. There is no pause.

首先需要注意的问题。

mailbox create

命令需要

--domain-uuid

参数，但目前没有

cargo-ai

命令可以列出发送域名——

domainManagement

API已存在，但尚未提供CLI交互界面。可从Cargo网页应用获取UUID，或在CDK仓库中使用

defineDomain

声明域名并从

cargo.state.json

中读取。请直接告知用户获取方式，而非猜测UUID。

bash

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"

```
--type
```
——可选值为
```
google
```
、
```
shared
```
或
```
private
```
。outlook
参数可被识别，但执行时总会失败，返回
```
transportNotSupported
```
错误：Graph传输功能尚未发布，因此Outlook邮箱无法投递邮件。请选择其他三个类型之一。
```
--username
```
——仅包含本地部分（如
```
jane@acme.com
```
中的
```
jane
```
）。会自动转换为小写；允许使用字母、数字、点、连字符和下划线，长度1–64字符，必须以字母或数字开头和结尾。
```
--first-name
```
/
```
--last-name
```
——收件人在From头部看到的名称。请使用真实身份的真实姓名；虚构发件人属于第2节中禁止的行为。
```
--signature
```
——HTML格式，存储在邮箱中（最大10,000字符）。

--folder-uuid

——类型为

mailbox

的文件夹UUID，来自

cargo-workspace-management

。

create

命令会立即返回

status: "pending"

——服务商尚未颁发凭据。当

refresh-status

命令显示状态变为

active

时，或等待5分钟后自动激活；在此之前尝试发送邮件会返回

credentialsMissing

错误。

bash

cargo-ai mailboxManagement mailbox list                        # 列出所有邮箱
cargo-ai mailboxManagement mailbox list --statuses active      # 逗号分隔，无空格
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"表示清除

cargo-ai mailboxManagement mailbox remove <uuid>               # 同时在服务商侧删除邮箱

```
--statuses
```
——可选值为
```
pending
```
、
```
active
```
、
```
inactive
```
，逗号分隔无空格。
```
inactive
```
状态表示邮箱被服务商禁用；
```
errorCode
```
字段会说明原因（如
```
401
```
表示认证失败，
```
402
```
表示垃圾邮件问题），修复前无法发送邮件。
```
none
```
是
```
--folder-uuid
```
和
```
--signature
```
参数的特殊值，表示「清除」。在
```
list
```
命令中，
```
--folder-uuid none
```
表示「列出未归类到任何文件夹的邮箱」。
```
remove
```
命令是停止月度计费的唯一方式。没有暂停功能。

Warm it up

暖箱操作

A mailbox that never starts warm-up is pinned at 5 real sends a day, forever. Warm-up is what moves it, and it takes 45 days to finish.

bash

cargo-ai mailboxManagement mailbox start-warmup <uuid> --daily-target 40
cargo-ai mailboxManagement mailbox get-warmup-stats <uuid>                    # next CLI release

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
```
— warm-up messages per day at full ramp, 1–40 (default 40). This is the provider's dummy traffic, not your send allowance.
```
--status
```
on
```
update-warmup
```
accepts the whole enum, but only
```
active
```
and
```
paused
```
do anything:
```
pending
```
and
```
failed
```
are states the provider reaches on its own, and
```
disabled
```
is what
```
stop-warmup
```
is for.
```
stop-warmup
```
resets the Cargo send ramp as well as tearing down provider warm-up — the mailbox drops back to 5/day and starts the 45 days over. Pause instead unless you mean it.

从未启动暖箱的邮箱将被永久限制为每天最多发送5封真实邮件。暖箱操作是提升发送额度的唯一方式，整个流程需要45天完成。

bash

cargo-ai mailboxManagement mailbox start-warmup <uuid> --daily-target 40
cargo-ai mailboxManagement mailbox get-warmup-stats <uuid>                    # 下一版本CLI将支持

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>                         # 重置发送额度递增流程

```
--daily-target
```
——暖箱完成后每天的模拟暖箱邮件数量，范围1–40（默认40）。这是服务商的模拟流量，并非您的实际发送额度。
```
update-warmup
```
命令的
```
--status
```
参数接受所有枚举值，但只有
```
active
```
和
```
paused
```
会生效：
```
pending
```
和
```
failed
```
是服务商自动进入的状态，
```
disabled
```
是
```
stop-warmup
```
命令的结果。
```
stop-warmup
```
命令会重置Cargo的发送额度递增流程，同时终止服务商的暖箱操作——邮箱会回落至每天5封的发送限制，需重新开始45天的暖箱流程。除非确实需要，否则请选择暂停而非停止。

Check the allowance before you send

发送前检查额度

bash

cargo-ai mailboxManagement mailbox get-send-allowance <uuid>

bash

cargo-ai mailboxManagement mailbox get-send-allowance <uuid>

→ {"allowance":{"dailyLimit":12,"sentCount":4,"remainingCount":8}}


Read `remainingCount` before enrolling a batch. Sends past it do not queue for tomorrow — they
fail immediately with `dailyLimitReached`, one wasted run per row.


在批量发送前请查看`remainingCount`字段。超过额度的发送请求不会排队到次日——会立即返回`dailyLimitReached`错误，每一行数据都会浪费一次运行机会。

Read what happened

查看操作记录

bash

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

Message vs thread vs event. A message is one outbound send. A thread is a conversation — its
```
lastEmail
```
and
```
lastEvent
```
are what you sort a reply queue on. An event is something that happened to a message (
```
sent
```
,
```
opened
```
,
```
clicked
```
,
```
replied
```
,
```
bounced
```
,
```
unsubscribed
```
). Inbound replies are events, not message rows; only outbound mail is a message.
```
--statuses
```
on
```
message list
```
/
```
thread list
```
is the list status —
```
pending
```
,
```
error
```
, or an event kind.
```
success
```
is not in that set: a delivered message reads as
```
sent
```
or later.
```
--kinds
```
,
```
--statuses
```
,
```
--reasons
```
are all comma-separated with no spaces.
bounced
never fires yet. Nothing parses delivery-status notifications, so bounces do not produce events and do not auto-suppress. Do not build a deliverability report that treats an empty bounce count as a clean list.

message

thread

, and

event

lists default to

--limit 50

(max 200) and return a

count

mailbox list

and

suppression list

have no default limit (max 1000), and

mailbox list

returns no

count

— see

references/response-shapes.md

bash

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

Message（邮件）vs thread（对话）vs event（事件）。Message指单发出站邮件；thread指一次完整对话——可通过
```
lastEmail
```
和
```
lastEvent
```
字段对回复队列进行排序；event指邮件发生的动作（
```
sent
```
、
```
opened
```
、
```
clicked
```
、
```
replied
```
、
```
bounced
```
、
```
unsubscribed
```
）。 inbound回复属于event，而非message；只有出站邮件属于message。
```
message list
```
/
```
thread list
```
命令中的
```
--statuses
```
参数指列表状态——可选值为
```
pending
```
、
```
error
```
或事件类型。
```
success
```
不在可选范围内：已投递的邮件状态显示为
```
sent
```
或更高阶状态。
```
--kinds
```
、
```
--statuses
```
、
```
--reasons
```
参数均为逗号分隔，无空格。
bounced
事件目前尚未触发。暂无解析投递状态通知的功能，因此 bounce不会生成事件，也不会自动添加到退订列表。请勿构建将bounce计数为空视为列表干净的投递报告。
```
message
```
、
```
thread
```
和
```
event
```
列表默认
```
--limit 50
```
（最大200），并返回
```
count
```
字段。
```
mailbox list
```
和
```
suppression list
```
命令无默认限制（最大1000），且
```
mailbox list
```
不返回
```
count
```
字段——详见
```
references/response-shapes.md
```
。

Suppression

退订管理

Workspace-wide, not per mailbox: a recipient opting out is opting out of the sender, not of one address the sender happens to own.

bash

cargo-ai mailboxManagement suppression list --reasons unsubscribed,manual
cargo-ai mailboxManagement suppression create --email opted-out@acme.com

Reasons are

unsubscribed

(the recipient's own choice, via

List-Unsubscribe

bounced

complained

, and

manual

suppression create

always records

manual

It is idempotent — suppressing an already-suppressed address returns the existing row.
Addresses are normalised (
```
trim().toLowerCase()
```
) on both write and check, so casing and stray whitespace cannot slip a suppressed recipient back into a send.
There is no
```
suppression remove
```
. That is deliberate.

退订列表为工作区全局范围，而非按邮箱划分：收件人退订是针对发送方，而非发送方拥有的某个具体地址。

bash

cargo-ai mailboxManagement suppression list --reasons unsubscribed,manual
cargo-ai mailboxManagement suppression create --email opted-out@acme.com

退订原因包括
```
unsubscribed
```
（收件人通过
```
List-Unsubscribe
```
主动选择退订）、
```
bounced
```
、
```
complained
```
和
```
manual
```
。
```
suppression create
```
命令始终记录为
```
manual
```
。
该操作具有幂等性——对已退订的地址执行屏蔽操作会返回已存在的记录。
地址在写入和校验时都会被标准化（
```
trim().toLowerCase()
```
），因此大小写和多余空格不会导致已屏蔽的收件人被重新纳入发送列表。
没有
```
suppression remove
```
命令。这是刻意设计的。

Pricing

价格查询

bash

cargo-ai mailboxManagement pricing get

bash

cargo-ai mailboxManagement pricing get

→ {"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}


Read this **live** before quoting a fleet cost — the figures above are what the workspace
returned at the time of writing, not a constant.


在报价邮箱集群成本前，请**实时**查询该命令——上述数值为撰写本文档时工作区返回的结果，并非固定值。

Sending: the

sendEmail

action

发送操作：

sendEmail

动作

Delivery is deliberately not in this CLI domain. It is a native orchestration action so that sends inherit orchestration's pacing, retry, and credit machinery:

bash

cargo-ai orchestration action execute \
  --action '{"kind":"native","actionSlug":"sendEmail","config":{}}' \
  --data '{"mailboxUuid":"<mailbox-uuid>","to":"jane@acme.com","subject":"...","bodyHtml":"<p>…</p>"}' \
  --wait-until-finished

0.1 credits per send, fixed.
```
config
```
stays
```
{}
```
; the inputs go in
```
--data
```
, like every other action (
```
../cargo-orchestration/SKILL.md
```
).
Optional
```
bodyText
```
(generated from the HTML when omitted),
```
inReplyTo
```
, and
```
references
```
.
To keep a reply threaded, send the whole chain.
```
references
```
is every
```
Message-ID
```
in the thread so far, oldest first — not just the parent. Mail clients break the thread otherwise.
The action is rate-limited per mailbox to that mailbox's own daily limit, spread across the day. A burst of 100 on a mailbox with 40 left fails the 41st immediately rather than parking it for a day.
A refused send is a node error, not a thrown exception.
```
recipientSuppressed
```
,
```
mailboxNotActive
```
, and
```
transportNotSupported
```
need a human and do not retry;
```
dailyLimitReached
```
,
```
credentialsMissing
```
, and
```
deliveryFailed
```
retry on their own.
There is no dry run from the CLI. The engine has one, but no
```
action execute
```
flag reaches it — the send is live the moment you run the command. Send to yourself first.

Threading, the full refusal table, and what Cargo injects into every message (unsubscribe header, open pixel, click redirect) are in references/sending.md
.

投递功能并未包含在本CLI模块中。它是一个原生编排动作，因此发送操作会继承编排的节奏控制、重试机制及credits计费规则：

bash

cargo-ai orchestration action execute \
  --action '{"kind":"native","actionSlug":"sendEmail","config":{}}' \
  --data '{"mailboxUuid":"<mailbox-uuid>","to":"jane@acme.com","subject":"...","bodyHtml":"<p>…</p>"}' \
  --wait-until-finished

每发送一封邮件收取0.1 credits，固定费用。
```
config
```
参数保持
```
{}
```
；输入信息放在
```
--data
```
中，与其他所有动作一致（详见
```
../cargo-orchestration/SKILL.md
```
）。
可选参数包括
```
bodyText
```
（省略时会从HTML自动生成）、
```
inReplyTo
```
和
```
references
```
。
如需保持回复线程连贯，请发送完整对话链。
```
references
```
参数需包含对话中所有
```
Message-ID
```
，按从旧到新的顺序排列——而非仅父邮件的ID。否则邮件客户端会中断对话线程。
该动作按每个邮箱进行速率限制，遵循邮箱自身的每日发送限额，并在全天内分散发送。若某邮箱剩余40封发送额度，一次性发送100封邮件时，第41封会立即失败，而非排队等待次日发送。
发送被拒绝会返回节点错误，而非抛出异常。
```
recipientSuppressed
```
、
```
mailboxNotActive
```
和
```
transportNotSupported
```
错误需要人工处理，不会自动重试；
```
dailyLimitReached
```
、
```
credentialsMissing
```
和
```
deliveryFailed
```
错误会自动重试。
CLI暂无试运行功能。引擎支持试运行，但
```
action execute
```
命令没有对应的参数——执行命令后邮件会立即发送。请先发送给自己测试。

对话线程规则、完整错误拒绝列表，以及Cargo自动注入每封邮件的内容（退订头部、打开像素、点击重定向），请查看**

references/sending.md

**。

Cost discipline

成本管控

This domain bills differently from the rest of the pack, and the difference is the thing to say out loud before provisioning anything.

A mailbox is a monthly, recurring charge — 100–160 credits per mailbox, per month, for as long as it exists. Five mailboxes is 500–625 credits every month, not once.
```
mailbox remove
```
is the only way to stop it; there is no pause. Quote the fleet size and the monthly credit estimate from a live
```
pricing get
```
, and get an explicit yes, before the first
```
create
```
.
Sends are 0.1 each, so volume is cheap and the fleet is not. Do the arithmetic in that order.
A play or scheduled tool that calls
sendEmail
re-bills on every run — and re-contacts the same people on every run, which is the §6 cadence gate in
```
acceptable-use.md
```
as much as a spend gate. Check
```
get-send-allowance
```
before enrolling a batch: rows past the allowance burn a run each and deliver nothing.
The full spend rules — sampling before a full enrollment, the approval message, the receipt — are
```
../cargo-gtm/references/cost-discipline.md
```
.

本模块的计费方式与其他模块不同，在配置任何资源前请明确告知用户这一点。

邮箱为月度 recurring charge——每个邮箱每月收取100–160 credits，只要邮箱存在就会持续计费。5个邮箱每月会产生500–625 credits的费用，而非一次性费用。
```
mailbox remove
```
是停止计费的唯一方式；没有暂停功能。在执行首次
```
create
```
命令前，请通过实时
```
pricing get
```
命令获取邮箱集群规模对应的月度credits估算费用，并获得用户的明确同意。
每发送一封邮件收取0.1 credits，因此发送量成本较低，而邮箱集群成本较高。请按此顺序进行成本计算。
调用
sendEmail
动作的play或定时工具会在每次运行时重新计费——并且每次运行都会重新联系相同的用户，这既是
```
acceptable-use.md
```
第6节中的频率限制，也是成本限制。在批量发送前请检查
```
get-send-allowance
```
：超过额度的行数据会浪费一次运行机会，且无法投递邮件。
完整的支出规则——批量发送前的抽样、审批消息、收据——详见
```
../cargo-gtm/references/cost-discipline.md
```
。

Declarative alternative:

defineMailbox

(CDK)

声明式替代方案：

defineMailbox

（CDK）

For the inbox itself, prefer CDK — the

mailbox create

help says so, and the reason is that a mailbox is long-lived infrastructure with a monthly cost, which is exactly what belongs in git and in a plan you can review.

defineMailbox

(with

defineDomain

for the sending domain) covers it;

adopt: true

binds a mailbox bought in the web app instead of provisioning a second one. See

../cargo-cdk/SKILL.md

and "Declarative vs imperative" in

../cargo/SKILL.md

Use this skill's imperative commands for one-off provisioning, and for everything CDK does not model at all: warm-up, allowance, messages, threads, events, and suppressions.

对于邮箱本身，优先使用CDK——

mailbox create

命令的帮助信息中也提到了这一点，原因是邮箱是长期存在的基础设施且产生月度费用，完全适合纳入git管理及可审核的计划中。

defineMailbox

（配合

defineDomain

配置发送域名）可覆盖邮箱配置；

adopt: true

参数可绑定在网页应用中购买的邮箱，而非重新配置一个新邮箱。详见

../cargo-cdk/SKILL.md

及

../cargo/SKILL.md

中的「声明式vs命令式」部分。

本技能的命令式命令适用于一次性配置操作，以及CDK未覆盖的所有功能：暖箱、额度管理、邮件、对话、事件及退订列表。

When the CLI surprises you

CLI异常处理

If a documented flag or response shape doesn't match what you observe, re-refresh the CLI and skills; if it still doesn't add up, file a report — it's read by the team. The missing

domainManagement

surface is a live example:

mailbox create

needs a

--domain-uuid

that no command can produce.

bash

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

若文档中记录的参数或响应格式与实际观察到的不符，请重新刷新CLI及技能；若问题仍存在，请提交报告——团队会查看报告。缺失的

domainManagement

交互界面就是一个典型例子：

mailbox create

命令需要

--domain-uuid

参数，但没有任何命令可以生成该参数。

bash

cargo-ai workspaceManagement report create \
  --title "<一行摘要>" \
  --description "<精确命令、errorMessage原文、预期vs实际结果、UUID>"

Presenting results

结果展示

../cargo/references/interaction.md

: lead with the outcome ("mailbox active, 8 of today's 12 sends left, 2 replies since Monday"), summarize a fleet or a reply queue as a compact table, and never dump raw

mailbox get

event list

JSON into the conversation. When you report a fleet, report its monthly cost, not a one-off one.

请遵循

../cargo/references/interaction.md

：以结果开头（如「邮箱已激活，今日12封发送额度剩余8封，周一以来收到2条回复」），将邮箱集群或回复队列总结为简洁表格，切勿将原始的

mailbox get

或

event list

JSON直接粘贴到对话中。报告邮箱集群时，请说明月度成本，而非一次性成本。

cargo-mailbox-management

Original

Translation

Cargo CLI — Mailbox Management

Cargo CLI — 邮箱管理

Bootstrap

初始化

Before any send — three checks

发送前的三项检查

The two numbers that govern a mailbox

控制邮箱的两个关键指标

Commands

命令说明

Provision a mailbox

配置邮箱

Warm it up

暖箱操作

Check the allowance before you send

发送前检查额度

→ {"allowance":{"dailyLimit":12,"sentCount":4,"remainingCount":8}}

→ {"allowance":{"dailyLimit":12,"sentCount":4,"remainingCount":8}}

Read what happened

查看操作记录

Suppression

退订管理

Pricing

价格查询

→ {"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}

→ {"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}

Sending: the
`sendEmail`
action

发送操作：
`sendEmail`
动作

Cost discipline

成本管控

Declarative alternative:
`defineMailbox`
(CDK)

声明式替代方案：
`defineMailbox`
（CDK）

When the CLI surprises you

CLI异常处理

Presenting results

结果展示

cargo-mailbox-management

Original

Translation

Cargo CLI — Mailbox Management

Cargo CLI — 邮箱管理

Bootstrap

初始化

Before any send — three checks

发送前的三项检查

The two numbers that govern a mailbox

控制邮箱的两个关键指标

Commands

命令说明

Provision a mailbox

配置邮箱

Warm it up

暖箱操作

Check the allowance before you send

发送前检查额度

→ {"allowance":{"dailyLimit":12,"sentCount":4,"remainingCount":8}}

→ {"allowance":{"dailyLimit":12,"sentCount":4,"remainingCount":8}}

Read what happened

查看操作记录

Suppression

退订管理

Pricing

价格查询

→ {"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}

→ {"monthlyCredits":{"google":125,"outlook":160,"shared":100,"private":100}}

Sending: the sendEmail action

发送操作：sendEmail动作

Cost discipline

成本管控

Declarative alternative: defineMailbox (CDK)

声明式替代方案：defineMailbox（CDK）

When the CLI surprises you

CLI异常处理

Presenting results

结果展示

Sending: the
`sendEmail`
action

发送操作：
`sendEmail`
动作

Declarative alternative:
`defineMailbox`
(CDK)

声明式替代方案：
`defineMailbox`
（CDK）