Cargo Mailbox Management

Cargo CLI — Mailbox Management

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`.

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. Everything on this page is live in the pinned CLI (1.0.66), including mailbox get-warmup-stats and the --daily-target default of 40 — both of which were merged-but-unpublished when this skill was written. 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 a missing subcommand here looks like a usage mistake rather than a stale install. cargo-ai mailboxManagement mailbox --help lists what your CLI actually has; re-run the session refresh in `../cargo/SKILL.md` to catch up.

Bootstrap

Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.

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.

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.

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.

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`](references/warmup-and-allowance.md). Read it before you promise anyone a send volume.

Commands

All commands output JSON. Reads need mailboxManagement:read; everything that provisions, updates, deletes, or suppresses needs 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.

Pricing a domain before buying it has the same gap, and one direct API call closes it: GET /v1/domainManagement/domains/search?name=<domain> returns available and priceCredits (where `null` means not purchasable, not free). The domain side of a fleet — that call, sizing domains by blast radius rather than capacity, the apex redirect, DMARC, naming, and why dnsRecords must stay undeclared — is [`references/sending-domains.md`](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, 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