AI エージェント向け

openemail agents は、Claude Code や Codex のような AI エージェント、または CI のスクリプト向けに、Markdown の短いガイドを表示します。人の手を借りずにサインインする方法、出力の読み方、コマンドの探し方、安全な変更の仕方、リストのページのたどり方、確認コードやスコープが足りないときの対処、そしてコピーして使える 5 つのレシピです。openemail agent も同じコマンドです。

openemail agentsopenemail agents --json | jq -r '.recipes[].commands[]'

--json を付けると、ガイドは schemaVersion、title、intro、{ id, title, points } の配列である sections、exitCodes、{ id, title, commands } の配列である recipes を持つ 1 つのドキュメントになります。これらのルールを毎回プロンプトに貼り付ける代わりに、プロジェクトがすでにエージェントに渡している指示ファイルで一度だけ、CLI を使う前に openemail agents を実行するよう伝えてください。

• —API キーを使います。OPENEMAIL_API_KEY を設定するか、1 つのコマンドに --api-key を渡します。キーは設定 → API キー（openemail open api-keys）で、エージェントに必要なスコープだけを付けて作成してください。キーはブラウザを開かず、確認コードも必要ありません。
• —または、人がこのマシンで一度 openemail login で行ったブラウザでのサインインを再利用し、--profile <name> で選びます。CLI はトークンを自分で更新します。
• —ターミナルがなければ何も尋ねません。--json、--no-input、CI のもとで、またはターミナルが接続されていない場合、CLI が尋ねるはずだった値は終了コード 2 で止まり、渡すべきフラグを示します。
• —ブラウザでのサインインは人が承認する必要があるため、無人の openemail login は何も登録しないうちに終了コード 2 とコード unattended で止まり、openemail login --with-token を案内します。
• —openemail whoami --json は、ワークスペース、サインインの種類、その scopes を表示します。

すべてのコマンドに --json を渡してください。すると stdout にはちょうど 1 つの JSON ドキュメント、--ndjson なら 1 行に 1 つのオブジェクトだけが出力され、進捗は stderr に出ます。失敗すると stderr に {"error":{...}} の行が 1 行出力されます。終了コードとその code で分岐し、next は人に見せ、文言が変わりうる message は決して解析しないでください。すべてのフィールドと終了コードは「スクリプト」のページにあります。

--help --json は、CLI が解析に使うのと同じコマンドレジストリから組み立てた 1 つの JSON ドキュメントとしてヘルプを出力するので、インストールされているバージョンと常に一致します。ルート、グループ、コマンドのどれでも使え、openemail help <command> --json も同じものを出力します。

openemail send --help --jsonopenemail domains delete --help --json | jq '.commands[0] | {scopes, destructive}'openemail help domains --json | jq -r '.commands[0].subcommands[].command'openemail --help --json | jq -r '.commands[].command'

ツリー全体は約 1 メガバイトで、そのほとんどは 198 のリソースコマンドです。必要なコマンドを指定するか、jq でツリーを絞り込んでください。テキストはバッククォートを保ち、色のコードを含みません。security のような非表示のコマンドも、hidden を true にして含まれます。

--dry-run は mcp serve 以外のすべてのコマンドで使えます。読み取りは通常どおり実行され、何かを変更する最初のリクエストは送られずに表示され、コマンドはそれ以外何もせずコード 0 で終了します。何も送らないので確認は省略され、エージェントは --yes を渡さずに、破壊的なコマンドが何をするかを確かめられます。

openemail domains delete <domain-id> --dry-runopenemail send --from [email protected] --to [email protected] --subject "Hi" --text "Hello" --dry-run --json

{  "dryRun": true,  "request": {    "method": "POST",    "url": "https://api.openemail.uk/emails",    "headers": {      "accept": "application/json",      "authorization": "Bearer [redacted]",      "content-type": "application/json",      "idempotency-key": "58e6fb61-ad2e-401e-b141-7a0546c7c749",      "user-agent": "openemail-cli/0.0.1 openemail-sdk/0.0.5"    },    "body": {      "from": "[email protected]",      "to": [        "[email protected]"      ],      "subject": "Hi",      "text": "Hello"    },    "raw": null  }}

• —変更とは、GET と HEAD 以外のすべてのリクエスト、MCP ツールの呼び出し、そして login と logout のサインインとサインアウトのリクエストです。トークンの更新と docs ask はそのまま実行されます。
• —計画には、メソッド、完全な URL、Authorization の値を Bearer [redacted] に切り詰めたヘッダー、Resend のキーのような秘密のフィールドを伏せた JSON 本文が表示されます。アップロードはサイズとコンテンツタイプだけを表示します。
• —profile use、login --with-token、保存済みの API キーの削除のように、このマシンの中だけで済む変更は {"dryRun":true,"local":{"action","profile"}} を出力し、何も保存しません。
• —最初の変更の前に読み取った内容を表示するコマンドは、それを先に表示します。read はスレッドを表示し、その後に既読にするリクエストを表示します。後者を省くには --no-mark-read を渡してください。
• —mcp serve は、何を送るかをクライアントが決めるため、--dry-run を終了コード 2 で拒否します。代わりに openemail mcp call <tool> --dry-run で 1 つのツール呼び出しをプレビューしてください。

すべてのコマンドは常に必要な API スコープを知っており、ヘルプにも一覧があります。保存済みのサインインにそのどれかが足りないとき、コマンドは API に現在の一覧を一度だけ問い合わせるので、サインイン後にウェブサイトで与えたアクセスもすぐに反映されます。それでもスコープが足りなければ、何かを尋ねたりリクエストを送ったりする前に、終了コード 4 とコード insufficient_scope で止まります：

{"error":{"type":"cli_error","code":"insufficient_scope","message":"This sign-in does not have the emails:send permission, which openemail send needs.","hint":null,"next":"Give this app more access in Account settings, Connected apps (openemail open apps, then Edit access), or run openemail login --force and choose more access.","status":null,"requestId":null,"param":null,"docUrl":null,"exitCode":4}}

• —ブラウザでのサインインの場合、next は、アカウント → コマンドラインでアプリにより多くのアクセスを与える（openemail open cli から「アクセスを編集」）か、openemail login --force を実行してより多くのアクセスを選ぶよう案内します。ブラウザでのサインインには keys:write や keys:manage が与えられないため、それらには API キーを案内します。
• —API キーの場合、next はそのスコープを持つキーを使うよう案内します。
• —--api-key や OPENEMAIL_API_KEY から来たキーは事前には確認されず、API が判断します。スコープが足りないために API が呼び出しを拒否したときも、エラーには同じ next が入ります。

API キーには確認コードは必要ありません。ブラウザでのサインインでは、webhook の追加、ルールの作成、メンバーの変更、ドメインの削除といった慎重を要する変更の前にコードが必要で、エージェントはそれを入力できません。そのため、エージェントを動かす前に、人が同じプロファイルでターミナルから openemail verify を実行するか、アカウント → コマンドラインでそのサインインに「60分間、変更を許可」を選びます。どちらでも以後 60 分間有効です。

openemail verifyopenemail verify --status --json

verify --status --json は、プロファイルが確認済みかどうかを elevated で、いつまでかを elevatedUntil でエージェントに伝えます。確認がなければ、変更は終了コード 4 とコード step_up_required で止まり、何も変わりません：

{"error":{"type":"cli_error","code":"step_up_required","message":"This action needs a verification code, and there is no interactive terminal to ask for one.","hint":null,"next":"Run openemail verify in an interactive terminal first, then run this again within 60 minutes. An API key never needs a code.","status":403,"requestId":"req_9Qm4tV","param":null,"docUrl":"https://openemail.uk/docs/api/errors#step_up_required","exitCode":4}}

MCP を話すエージェントは、代わりに OpenEmail の MCP サーバーを使えます。openemail mcp config --client claude-code、または codex、cursor など一覧にある他のクライアントを指定すると設定を表示し、openemail mcp serve はこの CLI のブラウザでのサインインを再利用するローカルのブリッジです。API キーは MCP サーバーに届きません。詳しくは「AI と MCP」のページをご覧ください。