cargo-mailbox-management

Cargo CLI — メールボックス管理

メールボックス。 メールボックスとは、ワークスペースが所有する実際の送信用受信箱です。ワークスペースが所有する送信ドメイン上に Cargo を通じてプロビジョニングされ、Cargo が SMTP と IMAP の認証情報を保持して、送信メールの配信と返信の受信に使用します。ここから導かれる重要な点は 2 つあり、どちらも誤解されやすいものです。メールボックスはレコードごとではなく、毎月発生する継続的なクレジット課金の対象であり、このドメインからメールを送信することはありません。受信箱をプロビジョニングしてウォームアップし、その結果を報告します。実際の送信は、cargo-orchestration の sendEmail アクションで行います。

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 を標準出力に出力します。失敗した場合は、{"errorMessage": "..."} を出力してゼロ以外の終了コードで終了します。このドメインの処理はすべて同期的です。各コマンドは 1 回の HTTP 呼び出しで完了するため、ポーリングする実行はありません。唯一、非同期に見える処理として、新規作成したメールボックスが pending のままになることがありますが、ポーリングには run get ではなく mailbox refresh-status を使用します。メールボックスへのアクセスには mailboxManagement:read／mailboxManagement:write 権限が必要です。管理者と編集者はどちらもこの権限を持っていますが、閲覧者は持っていません。作成または更新で権限エラーが返された場合、トークンは読み取り専用です（../cargo-workspace-management/SKILL.md）。スキル一式をインストールすると、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンのスコープ、管理者限定の機能が記載されています。

送信前の 3 つの確認事項

これは助言ではなく、送信を止めるための必須条件です。 Cargo がメールボックスを所有することで、送信ボタンを押す人は変わりますが、メッセージを送るべきかどうかは変わりません。適用される規則は ../cargo-gtm/references/acceptable-use.md §3 に記載されており、ここでも同じ内容が適用されます。最初の sendEmail の前に、以下の 3 点をすべて確認してください。送信後ではありません。

• 根拠 — この対象者には、どの許諾が適用されますか（顧客、オプトイン済みの連絡先、イベント参加者、または文書化された B2B の正当な利益に基づくケース）？
• 配信停止対象 — 対象者を補完または送信する前に、ワークスペースの配信停止リストを対象者から除外してください。suppression list は無料で利用でき、このドメインがその正式な参照元です。
• 関連性 — 受信者ごとに、なぜこのメッセージがその人に向けたものなのか、説明できますか？

どれか 1 つでも確認できなければ、作業を止めて確認を求めてください。Cargo 所有の送信には、固有の義務が 2 つあります。

• ウォームアップは上限であり、目標ではありません。 get-send-allowance は、メールボックスが今日送信できる数を報告します。これは上限まで送信するためのノルマではありません。上限の引き上げを求めること、同じ送信量を確保するために 1 つのキャンペーンを複数の新規メールボックスに分散すること、またはフィルターに各送信元からの送信数を少なく見せるために送信元を切り替えることは、設定に関する質問ではなく、acceptable-use.md §2 で禁止されている回避行為です。
• 配信停止は自動かつ絶対です。 すべての送信には署名付きの List-Unsubscribe ヘッダーが含まれます。受信者がこれを使用すると、ワークスペース全体に適用される suppression 行が登録され、エンジンは次回以降、そのアドレスへの送信を拒否します。この登録を削除するコマンドはありません。それが本来の動作です。配信停止対象を回避して、相手に再連絡することは決してしないでください。

メールボックスを左右する2つの数値

似ているように見えますが、意味は正反対です。これらを混同することが、メールボックスの健全性を読み違える最も一般的な原因です。

	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から利用できません。UUIDはCargoウェブアプリから取得するか、プロジェクトで defineDomain を宣言して cargo.state.json から読み取ってください。UUIDを推測せず、この点をユーザーに伝えてください。

購入前にドメインの価格を確認する場合も同じ制約がありますが、APIを1回直接呼び出せば確認できます。GET /v1/domainManagement/domains/search?name=<domain> は available と priceCredits を返します（null は購入不可を意味し、無料という意味ではありません）。フリートにおけるドメインの扱い――このAPI呼び出し、容量ではなく影響範囲に基づくドメイン数の見積もり、apexリダイレクト、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 はフラグで受け付けられますが、常に失敗します。Graphトランスポートはまだ提供されていないため、Outlookメールボックスからは配信できません。ほかの3つから選んでください。
• --username — ローカルパートのみを指定します（[email protected] の場合は jane）。小文字に変換されます。使用できるのは英字、数字、ドット、ハイフン、アンダースコアで、長さは1～64文字、先頭と末尾は英数字にしてください。
• --first-name / --last-name — 受信者に表示されるFromヘッダーの名前です。実在する本人の名前を、本人の正当なアイデンティティのもとで使用してください。架空の送信者は§2に基づく拒否対象です。
• --signature — メールボックスに保存されるHTMLです（最大10,000文字）。
• --folder-uuid — mailbox 種別のフォルダーです。cargo-workspace-management を参照してください。

create は status: "pending" の状態ですぐに戻ります。プロバイダーはまだ認証情報を発行していません。refresh-status がその状態を示した時点、または最長5分以内に自動的に 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"）。1時間ごとに再試行され、ログインに成功すると active に戻ります。
• none は、--folder-uuid と --signature の「クリア」を表すセンチネル値です。list で --folder-uuid none を指定すると、フォルダーに入っていないメールボックスを意味します。
• 月額課金を止めるには remove を実行します。一時停止する方法はありません。

ウォームアップする

ウォームアップを一度も開始していないメールボックスは、1 日あたり実送信 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 日あたりのウォームアップメッセージ数。1～40（デフォルトは 40）です。これはプロバイダーのダミートラフィックであり、実際に送信できる件数ではありません。
• update-warmup の --status は列挙型の値をすべて受け付けますが、動作するのは active と paused のみです。pending と failed はプロバイダーが自動的に移行する状態で、disabled にする場合は stop-warmup を使います。
• stop-warmup はプロバイダーのウォームアップを停止するだけでなく、Cargo の送信ランプもリセットします。メールボックスは 1 日 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

• メッセージ、スレッド、イベントの違い。 メッセージ は 1 件の送信メールです。スレッド は会話であり、返信キューの並べ替えには 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

• 送信 1 件につき 0.1 クレジットで固定です。このアクションには config がなく、他のすべてのアクションと同様、入力は --data に渡します（../cargo-orchestration/SKILL.md）。
• bodyText（省略時は HTML から生成）、inReplyTo、references は任意です。
• 返信をスレッドにまとめるには、スレッド全体を送信してください。 references には、親メッセージだけでなく、スレッド内のこれまでのすべての Message-ID を古い順に指定します。そうしないと、メールクライアントでスレッドが分断されます。
• アクションはメールボックスごとにレート制限され、そのメールボックス固有の日次上限が適用されます。また、送信 2 件の間にはランダムに 1～3 分の間隔が設けられます。残り 40 件のメールボックスに 100 件を一度に送信すると、40 件を送信し、残り 60 件は失敗せずに期間が更新されるまで待機します。
• 拒否された送信はノードエラーであり、例外はスローされません。 recipientSuppressed、mailboxNotActive、mailboxSendingPaused、mailboxNotFound、transportNotSupported は人による対応が必要で、再試行されません。dailyLimitReached、credentialsMissing、deliveryFailed は自動的に再試行されます。
• CLI からのドライランはできません。 エンジンにはドライラン機能がありますが、action execute のフラグでは実行できません。コマンドを実行した時点で送信が実行されます。まず自分宛てに送信してください。

スレッド化、拒否の全一覧、すべてのメッセージに Cargo が追加する内容（配信停止ヘッダー、開封ピクセル、クリックリダイレクト）については、references/sending.md を参照してください。

ワークフローからイベントを読み取る：listEmailEvents

CLI からは mailboxManagement event list で読み取れますが、ワークフロー内では、スレッドの配信イベントをネイティブアクション（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 で、新しい順に返されます。
• イベントの種類は sent、opened、clicked、replied、bounced、unsubscribed です。UI では「Viewed」と表示されますが、ワイヤー上の値は opened であることに注意してください。
• 各イベントは uuid、mailboxUuid、messageUuid、threadUuid、kind、occurredAt、actorEmail と、NULL 許容の url（clicked の場合）、inboundRfcMessageId、snippet を返します。
• bounced はまだ生成元がありません。配信状態通知を解析する仕組みがまだないため、これで絞り込んでも何も返らず、何の証明にもなりません。バウンス件数が 0 でも、リストに問題がないと報告しないでください。

コスト管理

このドメインでは、パックの他の部分とは異なる課金方式が適用されます。何かをプロビジョニングする前に、必ずこの違いを明確に伝えてください。

• メールボックスは毎月継続して課金されます。存在している限り、メールボックス 1 件あたり毎月 100～160 クレジットがかかります。メールボックスが 5 件なら、500～625 クレジットが一度だけでなく毎月発生します。課金を止める方法は mailbox remove のみで、一時停止はできません。ライブの pricing get でメールボックス数と月間クレジット見積もりを提示し、最初の create の前に明確な承認を得てください。
• 送信は 1 件あたり 0.1 クレジットなので、送信量のコストは低く、メールボックス群のコストは高くなります。この順番で計算してください。
• sendEmail を呼び出すプレイやスケジュール済みツールは、実行ごとに再課金されます。また、実行ごとに同じ相手へ再度連絡することになります。これは支出だけでなく、acceptable-use.md の §6 にある送信頻度の制限にも関わります。一括登録の前に get-send-allowance を確認してください。許容数を超えた行は後の期間まで待機し、許容数の約 15 日分を超えるバックログは、その実行期間内に処理しきれません。
• 全コストルール（全件登録の前のサンプリング、承認メッセージ、領収書）については、../cargo-gtm/references/cost-discipline.md を参照してください。

宣言型の代替手段：defineMailbox（プロジェクト）

受信箱自体には、プロジェクトを優先してください。mailbox create のヘルプでも推奨されており、その理由は、メールボックスは月額費用がかかる長期稼働のインフラであり、まさに Git に含め、確認可能なプランで管理すべきものだからです。defineMailbox（送信ドメインには defineDomain）で対応できます。adopt: true を指定すると、2つ目のメールボックスをプロビジョニングする代わりに、ウェブアプリで購入済みのメールボックスを紐付けます。../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 を会話にそのまま貼り付けないでください。メールボックス群を報告する場合は、一度限りの費用ではなく、月額費用を報告してください。