APIとMCPでアプリパスワードを管理

REST APIとMCPでは、通常メールボックスのアプリパスワードを一覧表示、作成、置き換え、取り消し、メールアプリのサインインモード変更、今後のメールボックスに適用するアカウントの既定値設定を行えます。このページは連携用のリファレンスです。ダッシュボードとウェブメールの手順は、デバイス用メールアプリのパスワードを参照してください。

アプリパスワードは、IMAP、SMTPのポート465と587、ManageSieve、CalDAV/CardDAVに使えます。新しいウェブメールやダッシュボードは開けません。クラシックウェブメールはIMAPでログインし、アプリパスワードを受け付けます。メールボックスの2FAは新しいウェブメールへのログインのみを保護します。メールアプリやクラシックウェブメールはコードを求めません。

この機能に、メールボックスのプランに基づく追加の制限はありません。既存のAPIとMCPのプラン権限は引き続き適用されます。APIスコープと権限を参照してください。

認証、スコープ、メンバー権限

/api/v1配下のRESTリクエストにはBearerトークンを使います。JSONでの書き込みにはContent-Type: application/jsonとIdempotency-Keyヘッダーを使います。

トークンのAPIスコープに加えて、メンバーのロールのパスワード設定権限も確認されます。メンバートークンと、メンバーが認可したコネクターが対象です。所有者のトークンに追加のパスワード設定スコープは必要ありません。メンバーの権限が不足していると403 scope_blocked_by_membershipが返ります。

ホスト型OAuthコネクターでは、対応するREST機能のスコープを使えます。従来のスコープセットでは、mail:readがmailboxes:readとaccount:readを付与し、mail:writeはさらにmailboxes:writeも付与します。スコープの展開によってメンバー権限や所有者限定のルールが無効になることはありません。

トークンのdomain_idsとmailbox_ids制約は、一括選択を含めて適用されます。機能が無効な間、アプリパスワードのエンドポイントと両方のモード変更エンドポイントは、認証とミドルウェアの確認後に404 not_foundを返します。アクセスできないメールボックスや存在しないメールボックスも404を返すため、すべての404が機能の状態を示すと判断しないでください。

エンドポイント一覧

以下のパスには/api/v1プレフィックスを含みます。{mailbox}は通常メールボックスのID、{id}はそこに属するアプリパスワードの行IDです。

この表のすべての書き込みにIdempotency-Keyが必要です。パスワードのエンドポイントは、既存の管理者用リセット操作であり、アプリパスワードの置き換えとは別です。

アプリパスワードの一覧と各行のフィールド

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

レスポンスのトップレベルにはmailbox_id、client_auth_mode、limit、active_count、行の配列であるdataがあります。limitはメールボックスごとに有効なパスワード25個です。有効な行が先頭に、新しい順で表示されます。取り消された行は90日間表示されます。一覧レスポンスに秘密の値は含まれません。

各行には次のフィールドが含まれます。

公開される取り消し理由は、revoked、rotated、mailbox_password_reset、mailbox_password_changed、login_suspended、converted_to_shared、mailbox_trashedです。プラットフォームが内部で発行する認証情報は一覧に含まれません。

アプリパスワードを作成する

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

nameは必須で、表示可能な文字1〜64文字を指定します。連続する空白は1つの空白にまとめられます。メールボックスは、ログインが停止されていない有効な通常メールボックスで、有効なアプリパスワードが25個未満である必要があります。

201レスポンスでは、dataに完全な行を返し、**data.password**を追加します。messageも含まれます。以下は、そのレスポンスに含まれる認証情報のフィールドの例です。

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

この例では、上記の他の行フィールドを省略しています。秘密の値は説明用の例です。実際の値は生成された小文字の英字16文字で、空白なしで返されます。アプリは空白や大文字も受け付けるため、利用者に表示する場合は4文字ずつ4つのグループに分けても構いません。

パスワードは一度だけ返されます。アプリケーションのログに記録しないでください。利用者は完全なメールボックスアドレスをユーザー名にして、メールアプリに直接入力します。作成や置き換えを行うと、メールボックスと設定済みの復旧メールアドレスに、アプリパスワードの名前を記載した通知が送られます。秘密の値は含まれません。ただし、新しいメールボックスと同時に発行される最初のアプリパスワードは例外です（後述）。

接続設定にはメールクライアント設定APIを使います。ダウンロードしたAppleプロファイルにパスワードは含まれません。インストール中にmacOSやiOSから求められたら、利用者がアプリパスワードを入力します。

新しいメールボックスと同時に最初のアプリパスワードを取得する

POST /api/v1/mailboxesとPOST /api/v1/mailboxes:bulkは、任意のboolean値**create_app_passwordを受け付けます。trueにすると、作成された各メールボックスに最初のアプリパスワードも発行され、app_passwordとして一度だけ返されます。内容は上記の行フィールドにpasswordを加えたものです。名前はCreated with the mailbox**です。メールボックスが新しく、呼び出し元がそのパスワードを受け取ったばかりのため、通知メールは送信されません。このフィールドを省略した場合（既定値はfalse）、レスポンスは変わりません。アプリパスワードが有効でない間は無視されます。

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

この場合、201レスポンスには、ウェブメール用のメールボックスのパスワードであるone_time_passwordと、メールアプリ用のapp_password.passwordが含まれます。一括レスポンスでは、作成された各行にそれぞれのapp_passwordが含まれます。発行できなかった場合、app_passwordはnullになります（単一作成では_app_password_warningも追加されます）。メールボックス自体は作成されるため、上記のエンドポイントでアプリパスワードを作成できます。単一作成を同じIdempotency-Keyでそのまま再試行すると、両方の秘密の値を含む同じレスポンスが返り、2つ目のアプリパスワードは発行されません。一括作成の再実行では、one_time_passwordと同様に秘密の値は省略されます。

パスワードを置き換える、または取り消す

置き換えにJSONボディは不要です。

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

200レスポンスには、data内の新しい完全な行、一度だけ返すdata.password、古い行を示すトップレベルのreplaced_id、messageが含まれます。置き換え後の行は**新しいdata.id**を持ち、名前は同じです。古い行はrevoked_reason: "rotated"で取り消され、その秘密の値は即座に無効になります。使用していたアプリはサインアウトします。デバイスに置き換え後のパスワードを入力してください。

新しいものを発行せずに取り消すには、次を使います。

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

ボディは不要です。200レスポンスにはstatus: "revoked"と、data内の取り消された完全な行があります。そのアプリはアクセスを失います。有効なアプリパスワードを持つ他のデバイスは、自動的に再接続します。取り消しは元に戻せません。取り消された行を新しいリクエストで置き換えたり取り消したりすると、409 conflictが返ります。

1つのメールボックスのメールアプリのサインインモードを変更する

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

modeは必須で、次の値を受け付けます。

• app_password_only：メールアプリにアプリパスワードを必須にします。メールボックスのパスワードを使う接続はサインアウトします。有効なアプリパスワードを使うアプリは自動的に再接続します。
• password_or_app_password：メールアプリがメールボックスのパスワードまたはアプリパスワードを受け付けます。

200レスポンスにはmailbox_id、client_auth_mode、messageがあります。現在のモードを再び指定すると、200を返して何も変更しません。モード変更は既存のアプリパスワードを取り消しません。

必須にする前にデバイス用のパスワードを作成してください。メールボックスのパスワードでのログインが拒否されると、"Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords."（ログインに失敗しました。このメールボックスはアプリパスワードのみを受け付けます。ウェブメールの設定 > アプリパスワードで作成してください。）と表示される場合があります。一般的なパスワードエラーだけを表示するアプリもあります。

共有メールボックスは直接ログインできず、このエンドポイントは422 mailbox_not_eligibleを返します。プラットフォームのシステムメールボックスはapp_password_onlyに切り替えられません。試みると422 system_mailbox_protectedが返ります。

どちらのモードも、新しいウェブメールへのログイン、すべての受信トレイ、Message APIトークン、メールボックスへのインポート、メールルール、転送に影響しません。共有メールボックスのメンバーは、自分の通常メールボックスの認証情報とモードを使います。

モードを一括変更する

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

modeと、次のセレクターのうち必ず1つを指定します。

すべての選択はアカウントとトークンの制約で絞り込まれます。アクセス範囲外のIDや未知のIDを明示すると、部分的に適用せず404を返します。未知のドメインや別アカウントのドメインは422 validation_errorを返します。セレクターが0個または複数なら422 invalid_selectionを返します。

一致するメールボックスは最大1000個です。超える場合は、変更前に422 selection_too_largeを返します。ドメインの範囲を絞るか、明示的なIDのバッチに分けて送信してください。

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matchedは選択されたメールボックス数、updatedは実際にモードが変更された数、skippedは共有、削除済み、削除中のメールボックス数です。アプリパスワードを必須にする場合は、システムメールボックスもskippedに含まれます。一時停止中やログイン停止中のメールボックスも、アクセス再開時に備えてモードを更新できます。すでに一致するメールボックスはmatchedだけに含まれ、updatedやskippedには含まれないため、同じ操作を安全に繰り返せます。停止中のアカウントは403で拒否されます。

メールボックスの状態を読み、アカウントの既定値を設定する

アプリパスワードが有効な間、GET /api/v1/mailboxesとGET /api/v1/mailboxes/{mailbox}のメールボックスリソースには、次のフィールドが含まれます。

• client_auth_mode：app_password_onlyまたはpassword_or_app_password。
• app_passwords_count：表示対象の有効なアプリパスワードの整数件数。プラットフォーム内部の認証情報は除きます。

機能が無効な間は両方のフィールドが省略されます。共有メールボックスには使用可能な直接ログインモードやアプリパスワードはありません。代わりに通常のメンバーメールボックスの認証情報をリクエストしてください。

GET /api/v1/accountにはaccount:readが必要です。通常のトップレベルフィールドであるid、name、email、plan、effective_plan_slug、subscription_status、limits、features、usage、safety_limits、created_atは引き続き利用できます。アプリパスワードが有効で、かつプラットフォームが新しいメールボックスにアカウントの既定値を適用する場合にのみ、**new_mailbox_client_auth_mode**が追加されます。それ以外でもGETは利用できますが、このフィールドは省略されます。

既定値を変更できるのはアカウント所有者のみです。

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

必須フィールドは同じ2つのモードを受け付けます。ここで書き込めるアカウントフィールドはこれだけです。レスポンスのトップレベルにはid、new_mailbox_client_auth_mode、messageがあります。このフィールドを公開するための両方の条件を満たさなければ、PATCHは404を返します。メンバートークンやメンバーが認可したコネクターには403 scope_blocked_by_membershipを返します。

所有者のトークンでもdomain_idsまたはmailbox_idsで制限されている場合は403 token_resource_constrainedが返ります。リソース制限のない所有者のトークンを使用するか、アカウント設定で既定値を変更してください。

既定値は、今後ダッシュボード、一括作成、招待、API、エージェントで作成するメールボックスに適用されます。既存のものは変更しません。APIで1つのメールボックスを作成する際は、POST /api/v1/mailboxesにclient_auth_modeを明示できます。省略するとアカウントの既定値に従います。機能の提供開始時に、既存のメールボックスはpassword_or_app_passwordを維持します。新しいメールボックスの既定値は、所有者が変更しない限りapp_password_onlyです。

メールボックスのパスワードリセットはアプリパスワードを自動的に取り消す

POST /api/v1/mailboxes/{mailbox}/passwordにはmailboxes:write、同じメンバーのパスワード設定権限、Idempotency-Keyが必要です。ボディの必須フィールドpasswordには、メールボックスのパスワードポリシーを満たす新しいメールボックスのパスワードを指定します。アプリパスワードの作成エンドポイントではありません。

このエンドポイントからの管理者によるリセットが成功すると、MCPエージェントによるパスワード変更も含め、すべてのアプリパスワードがmailbox_password_resetの理由で取り消されます。取り消しを回避する選択肢はありません。機能が有効な間、レスポンスにはstatus、sync_pending、messageとともに、整数件数のapp_passwords_revokedが含まれます。

• メールサーバーとの同期が完了した場合は、200、status: "updated"、sync_pending: false。
• パスワードを保存して同期を待っている場合は、202、status: "update_pending"、sync_pending: true。この時点でアプリパスワードはすでに取り消されています。

リセットは既存のメールボックスのメッセージトークンも取り消します。これはメールボックスのパスワードリセットの結果であり、個別のアプリパスワードの置き換えやメールアプリのモード変更によるものではありません。

ウェブメールでのセルフサービスのパスワード変更は、利用者がすべてのアプリパスワードも取り消すを選択した場合だけアプリパスワードを取り消します。パスワード復旧、ログイン停止、共有メールボックスへの変換、最近削除した項目への移動はすべて取り消します。アクセスやメールボックスを復元しても、取り消された秘密の値は戻りません。APIによるメールボックスのログイン停止を参照してください。

冪等性と一度だけ返す秘密の値

意図した書き込みごとに新しいIdempotency-Keyを使い、同じメソッド、パス、ボディの通信再試行に限って再利用します。キーは必須で、最大255文字です。成功したレスポンスは既定の24時間キャッシュされます。別のリクエストに同じキーを使うと409 idempotency_mismatchが返ります。

アプリパスワードの作成や置き換えを再実行すると、同じ安全な識別子が返りますが、data.passwordは省略されます。_idempotency_replay_warningとレスポンスヘッダーX-Idempotency-Replayed: trueが含まれます。再実行で失った秘密の値を取り戻すことはできません。返されたdata.idを使い、新しいキーで有効な行を置き換えて、使用可能な新しいパスワードを取得します。置き換え後の新しいIDを追跡してください。

成功した取り消しを同じキーで再実行すると、保存された結果を返します。取り消された行に新しい取り消しリクエストを送ると、409 conflictを返します。モード変更は繰り返しても同じ結果になりますが、意図した変更ごとに新しいキーを使ってください。モードを切り替えた後で以前のキーを再利用すると、新しい意図を適用せず古いレスポンスを再送する場合があります。

レート制限とエラー

作成はアカウントごとに1時間60回、置き換えはアカウントごとに1時間30回に制限されます。APIとMCPの呼び出し元が同じアカウント上限を共有し、トークンごとの別枠ではありません。一括モード変更には、追加で1分10リクエストの制限があります。通常のAPI制限も適用され、既定値は認証情報ごとに1分60リクエストです。制限されたリクエストは429 rate_limitedを返します。Retry-Afterヘッダーに従ってから再試行してください。

エラーは、code、message、hint、request_id、retryableを含む標準のerrorオブジェクトです。文章の一致ではなく、機械可読コードで処理してください。

MCPツールと破壊的操作の制御

MCPはRESTと同じ認可とレスポンスフィールドを使います。直接操作するツールは次のとおりです。

メールボックス作成ツールのcreate_mailbox_generated_passwordとbulk_create_mailboxesも、RESTと同じ任意のcreate_app_password入力を受け付けます。

書き込みツールは任意のidempotency_keyも受け付けます。メールボックスのモード変更でRESTが使うボディフィールドはmodeですが、MCPツールの入力名は**client_auth_mode**です。一括セレクターには、RESTと同じアクセスルールと1000メールボックスの上限が適用されます。

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

セルフホストのサーバーでは、上記のすべての書き込みに**TREKMAIL_ALLOW_DESTRUCTIVE=true**が必要です。認証情報の作成もメールボックスへのアクセスを付与するため、制御対象です。一覧表示とアカウントの読み取りにはこのフラグは不要です。書き込みを実行する前に、意図する認証情報やアクセスの変更について利用者の承認を求めてください。秘密の値を直接返すツールは、パスワードを一度だけ表示して利用者にアプリへ貼り付けてもらい、ファイルやメモリに保存せず、後のメッセージやツール呼び出しで繰り返さないようエージェントに指示します。

ChatGPT/OpenAIとClaudeのディレクトリプロファイル

これらのプロファイルは、チャット内で秘密の値を発行する代わりに、作成や置き換え用の安全なダッシュボード設定リンクを返します。これらのプロファイルではメールボックスの作成もダッシュボードへのリンクになるため、最初のアプリパスワードはcreate_app_passwordではなく、ダッシュボードのメールボックスを作成しましたカードから受け取ります。リンク先は/app/mailboxes/{mailbox_id}/security#app-passwordsです。利用者はそこでログインして操作を完了します。

OpenAIプロファイルは**get_mailbox_app_password_setup_linkとget_mailbox_app_password_replacement_setup_linkを公開します。Claudeプロファイルはcreate_mailbox_app_passwordとrotate_mailbox_app_password**の名前を維持しますが、data.passwordではなく安全な設定リンクを返します。これらのディレクトリツールが秘密の値を返すと案内したり、利用者にチャットへ貼り付けるよう求めたりしないでください。

接続情報にはget_mail_client_setupを使います。コネクター全般の設定は、AIエージェントの接続を参照してください。White Labelメールボックスでも同じAPI機能とブランドのウェブメール、メールホストを使います。利用者向けの説明では認証情報をアプリパスワードと呼んでください。