キー、メンバー、ロール

これらのコマンドは、誰が、何がワークスペースにアクセスできるかを決めます。openemail keys は API キーを管理し、それぞれの操作を読みます。openemail members はワークスペースのメンバーとその招待を管理し、openemail roles はメンバーやキーができることを定義します。openemail me は呼び出しに使っているキーやサインインを説明し、openemail languages は翻訳付きの送信が受け付ける言語を一覧表示します。使い捨て受信トレイにはサインインがまったく不要です。普段使うのは openemail temp で、openemail temp-mail はその背後にある API のすべての呼び出しです。openemail api は、他のコマンドが扱わない任意のエンドポイントに届きます。

• —キーのコマンドは、keys list に表示されるとおり、oe_live_ の後の 16 進数 24 文字であるキー ID を受け取ります。メンバーのコマンドは、メールアドレスではなく、members list の userId であるアカウント ID を受け取ります。ロールには名前での検索がないため、ロールのコマンドは roles list から得られる role_ の ID を受け取ります。
• —名前空間は key、member、role、language、tempMail でも使えます。ls、show、new、edit、rm など、いつもの動詞の別名が使えます。動詞が add と remove の members では、new と create は add に、rm、del、delete は remove になります。
• —openemail <command> --help は、すべての引数とフラグを、その型、呼び出しに必要なスコープ、メソッドとパス、返ってくるものとともに一覧表示します。--json を付けると、同じページをデータとして出力します。

キーを読むには keys:read が、すべての変更には keys:manage が必要です。ブラウザでのサインインには keys:write も keys:manage も決して付与されないため、キーの作成、変更、ローテーション、取り消し、削除には keys:manage を持つ API キーか Web アプリ（openemail open api-keys）が必要です。keys:read を持つブラウザでのサインインがキーを読めるのはワークスペースのオーナーの場合だけで、メンバーのサインインは 403 owner_only で拒否されます。

• —keys create、keys rotate、me rotate はキーのシークレットを token に 1 回だけ表示し、CLI は二度と表示されないことを警告します。読み取りではすべて代わりに maskedKey が表示されます。
• —省略した場合、新しいキーは emails:send だけを持ち、作成したキーのロール、送信範囲、有効期限を引き継ぎます。--domain-allowlist と --address-allowlist で送信元として使えるアドレスを設定し、--expires-in-minutes は 5 から 5,256,000（10 年）を受け付けます。
• —キーが自分より広い権限のキーを作ったり、それにアクセスしたりすることはありません。スコープ、ロール、有効期限、モード、送信範囲はすべて呼び出し元のキーの範囲内でなければならず、そうでなければ呼び出しは 403 beyond_caller_authority で拒否され、param で広すぎたものが示されます。一部のドメインやアドレスに絞られたキーには、自身の送信範囲内のキーしか見えず、それ以外は 404 になります。
• —keys update は送ったものを置き換えます。--scopes、--address-allowlist、--domain-allowlist はそれぞれ新しいリスト全体を受け取り、省略したフラグはそのまま残ります。--no-enabled はキーをオフにし、そのキーでの呼び出しはすべて inactive_api_key で拒否されます。--enabled で元どおりに戻ります。これで、元に戻せる方法でキーを止められます。
• —keys revoke は恒久的です。キーを再びオンにすることも、ローテーションや変更をすることもできなくなります。keys delete は取り消したキーだけを削除し、それ以外は 409 not_revoked で拒否されます。削除したキーのリクエストログとアクティビティは「削除されたキー」として残ります。
• —keys rotate には重複期間がないので、新しいシークレットが返った瞬間に古いシークレットは使えなくなります。そのキーが保存済みのプロファイルで使っているものであれば、CLI は新しいシークレットをそのプロファイルに保存するので、引き続き動作します。OPENEMAIL_API_KEY や --api-key のキーは保存できないので、CLI は古いキーを保管していた場所に新しいトークンを保存するよう伝えます。

リクエストログは、キーが行ったすべての呼び出しを記録します。メソッド、パス、ステータス、エラーコード、所要時間、IP、ユーザーエージェントで、本文やクエリ文字列は決して含みません。何も削除されないので、キーの最初の呼び出しまでさかのぼれます。ブラウザでのサインインで行った呼び出しは含まれません。アクティビティログは、キーへのすべての変更と、そのキーを提示して拒否されたすべての呼び出しを auth_failed として記録し、誰が変更したかを actor に記録します。

• —list-requests と list-activity は 1 つのキーを読みます。list-workspace-requests と list-workspace-activity は、見えるすべてのキー、または --key-ids で指定した最大 50 個のキーを、削除したキーも含めて読みます。
• —--since と --until は期間を絞り込み、2026-09-01T00:00:00Z のような ISO 8601 の日時を受け取ります。--failed-only はステータスが 400 以上で応答された呼び出しだけを残します。

呼び出しが拒否されたときに最初に実行するコマンドは openemail me get です。スコープが不要なので、有効なキーやサインインであれば何でも自分自身を説明できます。

• —scopes は認証情報が今できることで、作成時のスコープを発行元のロールで絞り込んだものが、リクエストのたびに計算されます。grantedScopes は作成時のスコープで、roleId はロールを示します。grantedScopes にあって scopes にないスコープは、ロールによって外されたものです。スコープを持っているように見えるキーで 403 insufficient_scope になるのはたいていこれが理由で、別のキーを発行するのではなくロールを変更して直します。
• —domainAllowlist と addressAllowlist は送信元として使えるアドレスを示します。両方とも null なら、ワークスペースが持つ任意のアドレスです。
• —ブラウザでのサインインの場合は、そのサインインを説明します。object は oauth_token、clientId はこの CLI の接続済みアプリを示し、expiresAt は承認が終わる日時で、終わらない場合は null です。
• —me ping は同じスコープの詳細付きで ok: true を返しますが、許可リストは含まないので、正常性チェックに向いています。取り消された、期限切れの、オフにされた、または入力を誤ったキーは 401 と終了コード 3 で失敗します。
• —me rotate は呼び出しに使っているキーに新しいシークレットを与えます。ブラウザでのサインインが決して持たない keys:write が必要なので、API キーが必要です。キーのそれ以外の設定はそのまま残り、古いシークレットはすぐに使えなくなり、keys rotate と同じく保存済みのプロファイルには新しいものが保存されます。応答が失われると、誰も見ていないシークレットのままキーが残ることがあり、その場合は Web アプリで新しいシークレットが必要になります。
• —openemail whoami は同じ応答を人が読みやすい形で表示します。

openemail languages list は言語の表全体（約 200 行）を 1 回の応答で表示し、各言語のコード、英語名、現地語名、旗、右から左に書くかどうかを示します。翻訳付きの送信の対象には、コード、英語名、現地語名のどれでも使えます。サインインは必要ですが、スコープは不要です。openemail ai languages は同じ表を --search フラグ付きで表示し、サインアウトしている場合は CLI に同梱された表を表示します。

メンバーは、決して統合されない 2 つのものを持ちます。ロールは何ができるかを示し、アドレスとドメインの付与はどのメールに対してできるかを示します。付与にはそれぞれ独自のアクセス権があり、member は読み取りと送信、viewer は読み取りだけです。送信には両方が必要なので、emails:send を持つロールでも、アドレスへの付与が viewer ならそのアドレスからは送信できません。ドメイン全体の付与は、後で作られたものも含め、そのドメインのすべてのアドレスを対象にします。

• —members list はワークスペースのオーナーを isOwner の印付きで先頭に置くので、席数を数えるときはその行を除いてください。オーナーはすべての権限を持ち、招待、変更、削除はできません。また、すでにワークスペースにいる人を再び招待することもできません。どちらも 422 member_is_owner になります。
• —アドレスの付与は持っているがロールを与えられたことのない人は implied: true 付きで返り、ロールは付与から推定されます。members update で正式なロールを与えられます。
• —members add は、すでにアカウントを持っている人にも招待を送ります。承諾されるまで何も付与されず、承諾されると招待に含まれるロール、アドレス、ドメインがそのまま付与されます。10 分以内に同じアドレスを再び招待すると 409 invitation_too_soon になり、それ以降は 2 通目を送る代わりに保留中の招待を更新します。
• —resend-invitation はさらに 14 日間有効な新しいリンクを送り、古いリンクを無効にします。これで期限切れの招待も更新されます。revoke-invitation は招待を取り下げますが、すでに承諾された招待は 409 invitation_accepted になるので、代わりにメンバーを削除してください。
• —members update はロールだけを変更します。grant-address は 1 つのアドレスを付与するか、そのアクセス権を変更するので、別の --access でもう一度実行すると、2 つ目を追加するのではなく付与が変更されます。revoke-address は 1 つのアドレスを取り上げ、残りはそのままにします。推定されたメンバーの最後の付与を取り消すと、その人はワークスペースから外されます。
• —members remove は、その人のワークスペースへのアクセス、メンバーシップ、すべての付与を終わらせ、取り消されたアドレスの付与の数を addressesRevoked で報告します。その人のアカウントと送信したメールには手を付けません。

ロールは、その下で発行された API キーの上限でもあります。キーができることは、キー自身のスコープをロールの権限で絞り込んだもので、リクエストのたびに計算されます。

• —roles list は、あらかじめ用意されたロールを Owner、Admin、Member、Viewer、Developer、Billing の順に先頭に表示し、その後にカスタムロールを名前順に表示します。ワークスペースに作れるカスタムロールは最大 24 個で、それを超えると roles create は 422 role_limit_reached になります。
• —ロールは、その権限が含意する権限も保存するので、templates:write は templates:read も保存し、roles:write は roles:read と members:read を伴います。リストは推測せず、応答から読み直してください。
• —roles update --permissions はリスト全体を置き換えるので、ロールを読み、リストを変更し、すべてを送ってください。--description null は説明を消去します。変更は、そのロールを持つすべてのメンバーとキーの次の呼び出しから有効になります。
• —Owner 以外のすべてのロールは、あらかじめ用意されたものも含めて、名前の変更、書き換え、削除ができ、削除したあらかじめ用意されたロールは戻りません。オーナーのロールは、編集には 409 role_immutable、削除には 409 role_undeletable を返します。
• —いずれかのメンバー、API キー、保留中の招待がロールを持っている間、roles delete にはそれらを引き継ぐロールを指定した --reassign-to が必要で、なければ 409 role_in_use で拒否されます。取り消されたキーもロールを指したままなので、apiKeys の数が 0 のロールでも必要な場合があります。応答では、移された人数が reassigned、キーの数が keysReassigned として報告されます。
• —roles list-permissions は権限の一覧全体を、それぞれラベルとグループ付きで表示します。billing:write や workspace:manage など一部は scope: false で返ります。ロールは持てますが、キーは持てません。

使い捨て受信トレイにはアカウントもサインインも不要です。独自の受信トレイトークンでアクセスし、トークンは oe_inbox_ で始まり、受信トレイの作成時に 1 回だけ返されます。普段は openemail temp を使い、残りの延長回数、延長、添付ファイルのバイト列など、temp が示さないフィールドや手順が必要なときは openemail temp-mail を使います。

• —どちらもトークンを、自分だけが読める ~/.openemail/temp-mail.json に保存します。temp new と temp-mail create がトークンを保存し、temp list はどちらの方法で作った受信トレイも表示し、どちらの削除でもトークンは忘れられます。保存済みの受信トレイは、コマンドが ID を求める場所ならどこでもアドレスで指定できます。
• —この CLI が作成していない受信トレイには、--inbox-token でトークンを渡してください。保存済みのトークンも渡されたトークンもない場合、コマンドは何も送らないうちに終了コード 3 で停止します。
• —2 つの作成コマンドはフラグの名前が異なります。temp new は --name、--domain、--ttl を、temp-mail create は --local-part、--domain、--ttl-minutes を受け取ります。ローカルパートは英字、数字、ドット、ハイフン、アンダースコアで 3 から 32 文字、英字か数字で始まって終わる必要があり、postmaster などの名前は拒否されます。リース期間は 1 から 1440 分で、既定は 60 分です。
• —各 IP アドレスは 1 時間に 6 個、1 日に 30 個の受信トレイを作成でき、それを超えると 429 too_many_inboxes（終了コード 8）になります。すでに持っている受信トレイの延長は数えられないので、この上限への対処は temp-mail extend です。
• —temp-mail extend は最大 1 時間延長しますが、受信トレイの作成から 24 時間を超えることはなく、延長は最大 23 回です。応答の extensionsLeft を読んでください。0 になると、以降はずっと 409 extension_limit になります。
• —temp-mail list-messages は 1 ページに 1 から 50 通（既定は 50 通）のメッセージを読み、それぞれに最大 400 文字のプレーンテキストの snippet が付きます。そこにはワンタイムコードが含まれていることがよくあります。ページを超えた分が捨てられることはなく、--all ですべてのページをたどれます。
• —temp read、temp-mail get-message、temp-mail list-attachments でメッセージを読むと既読になります。2 MB を超える本文は切り詰められ、truncated でそれがわかります。8 MB を超える添付ファイルはそもそも保存されないので、その content は null です。
• —受信トレイを削除するとそのメールはすぐに削除されますが、アドレスは本来のリース終了から 7 日後まで予約されたままで、それまでに同じアドレスを求めると 409 address_taken になります。

openemail api <method> <path> は他のすべてのコマンドと同じ通信経路で 1 つのリクエストを送るので、プロファイルやキー、トークンの更新、確認コード、確認がすべて適用されます。パスだけなら GET で、JSON の応答は整形して表示されます。openemail api /keys/self は me get の背後にある呼び出しです。

• —-d、--data は本文を、インラインの JSON、@path によるファイル、または - による stdin から受け取ります。-q、--query と -H、--header は key=value を受け取り、繰り返し指定できます。-o、--out は応答を受け取ったままファイルに保存します。
• —DELETE と、キーの取り消しやローテーションなど、リソースコマンドなら確認を求める呼び出しは、まず確認を求め、無人実行では --yes が必要です。
• —失敗したリクエストは API のエラーを表示し、対応するコードで終了します。

security 名前空間は openemail verify が操作するため、openemail --help には表示されません。その動詞 step-up-status、begin-step-up、verify-step-up は verify が行う呼び出しです。verify --status はステータスを読み、verify はコードを要求し、入力を求めて確認します。これらはブラウザでのサインインのためのもので、API キーではどれも 400 step_up_not_applicable で拒否され、openemail verify はキーにはコードが不要であることを伝えます。

openemail keys create --name 'Billing sender' --scopes emails:send \  --domain-allowlist billing.acme.com --expires-in-minutes 129600 --json \  | jq -r .token | openemail login --with-token --profile billingopenemail whoami --profile billing

OPENEMAIL_API_KEY を通すなどして、keys:manage を持つ API キーで実行してください。シークレットは応答から新しいプロファイルへ直接渡されるので、画面やファイルに出ることはありません。このキーは billing.acme.com からしか送信できず、90 日で期限切れになります。

openemail keys list --all | jq -r 'select(.status != "active") | [.name, .status, .lastUsedAt] | @tsv'openemail keys list-workspace-requests --failed-only --since 2026-09-26T00:00:00Z --all \  | jq -r '[.createdAt, .keyName, .status, .errorCode, .method, .path] | @tsv'

id=4c1b257a66287fd113bd89d0openemail keys update "$id" --no-enabledopenemail keys list-activity "$id" --since 2026-09-27T00:00:00Z --all | jq -r 'select(.type == "auth_failed") | .createdAt'openemail keys revoke "$id" --reason 'Contractor offboarded' --yesopenemail keys delete "$id" --yes

先にキーをオフにする操作は --enabled で元に戻せます。それでもそのキーを提示する呼び出しはすべて拒否され、アクティビティに auth_failed として現れるので、まだ何がそのキーに依存しているかがわかります。取り消しは元に戻せず、削除できるのは取り消したキーだけです。

openemail roles list-permissions --json | jq -r '.[] | [.group, .id, .label] | @tsv'role=$(openemail roles create --name Support --permissions threads:write,emails:send,templates:read \  --description 'Answers help@ and nothing else.' --json | jq -r .id)openemail members add --email [email protected] --role-id "$role" \  --domain-ids 93542ff8-2baa-4f2f-841d-5ceaa074ab0d --access memberopenemail members list-invitations

指定した権限が含意するため、ロールは threads:read と emails:read も持った状態で返ります。Sam にロールとドメイン全体が付与されるのは、招待を承諾してからです。ブラウザでサインインしている場合、members add はまず確認コードを求めます。

old=role_8b1f4c2e9a7d3b60e5f1a2c4new=role_2c7e9a1f4b8d3e60c5a7f1b9user=$(openemail members list --all | jq -r 'select(.email == "[email protected]") | .userId')openemail members update "$user" --role-id "$new"openemail roles get "$old" --json | jq '{name, members, apiKeys}'openemail roles delete "$old" --reassign-to "$new" --dry-runopenemail roles delete "$old" --reassign-to "$new" --yes

members と apiKeys は問い合わせた時点で数えられるので、削除によって何が移されるかがわかります。ドライランは、クエリに reassignTo を含む DELETE を送らずに表示します。ブラウザでサインインしている場合、更新と削除はそれぞれ確認コードを求めるので、スクリプトで行うときは先に openemail verify を実行してください。

address=$(openemail temp new --ttl 15)openemail send --from [email protected] --to "$address" --subject 'Delivery check' --text 'Your code is 482913' --yesopenemail temp watch "$address" --first --json | jq -r .snippet | grep -oE '[0-9]{6}'openemail temp delete "$address" --yes

temp new はアドレスだけを表示するのでシェル変数に収まり、temp watch --first は最初のメッセージで止まります。openemail send の代わりに登録フォームをそのアドレスに向ければ、同じ方法で確認コードを受け取れます。

• —スコープのないサインインやキーは終了コード 4 で停止し、足りないスコープの名前と取得方法を示します。
• —次のコマンドは確認を求めます。keys delete、rotate、revoke、me rotate、roles delete、members remove、revoke-address、revoke-invitation、temp delete、そして temp-mail delete と delete-message です。いいえと答えると終了コード 10 で終了し、何も変更しません。--yes なしの無人実行では、何も送らないうちに終了コード 2 で停止します。
• —ブラウザでサインインしている場合、roles update と roles delete、そして members add、update、remove、grant-address、revoke-address は、このサインインで過去 60 分以内に確認していない限り、確認コードも求めます。--yes でこれを省略することはできず、無人実行では誰も入力できないので、コマンドは終了コード 4 で停止します。先に openemail verify を実行してください。API キーが求められることはありません。
• —--dry-run は変更が送るはずのリクエストを本文とともに表示し、送信も確認もせずに終了コード 0 で終了します。
• —リストは 1 ページを読みます。--limit は 1 から 100 を受け付け、省略するとサーバーは 25 件を返します。例外は temp-mail list-messages で、1 から 50 を受け付け、50 件を返します。--cursor は前のページの nextCursor を受け取ります。--all はすべてのページを読み、--max <n> はその件数で停止し、--ndjson、またはパイプでの --all は 1 行に 1 つの JSON オブジェクトを出力します。--json を付けると、リストは 1 つの { items, hasMore, nextCursor } ドキュメントを出力します。
• —roles list-permissions、languages list、temp-mail list-domains、temp-mail list-attachments は、ページなしで、すべてを単純な配列として一度に返します。
• —拒否された場合は、そのステータスに対応するコードで終了します。401（取り消されたキーなど）なら 3、403（beyond_caller_authority や owner_only など）なら 4、404 なら 5、409（not_revoked、role_in_use、invitation_too_soon など）なら 6、400 か 422（member_is_owner や role_limit_reached など）なら 7、429（too_many_inboxes など）なら 8 です。
• —2 回行うと重複してしまう変更は、ネットワーク障害の後に再試行されることはありません。keys create と rotate、me rotate、roles create と delete、members add、remove、revoke-address、resend-invitation、そして temp-mail create、extend、delete、delete-message です。もう一度実行する前に確認してください。読み取りと、keys update、keys revoke、roles update、members update、grant-address のように 2 回行っても同じ結果になる変更は、自動で再試行されます。