APIスコープとプラン権限のガイド

スコープはAPIトークンが実行できる操作を正確に制御します。各トークンには一連のスコープがあり、APIはリクエストのたびにそれらを確認します。

スコープの仕組み

トークンを作成するときに、含めるスコープを選択します。APIはすべてのリクエストに3つの上限を適用します。

1. アカウントの権利： 現在のプランと有効なアドオンが、現時点で利用できる機能を決定します。
2. メンバーシップ： 委任されたユーザーは、現在の役割とドメインアクセスを超える権限を付与または使用できません。
3. 認証情報への付与： トークンまたはOAuth同意に、エンドポイントが要求するスコープが含まれている必要があります。

エラーは通過できなかった上限を示します。insufficient_scopeは認証情報にスコープが付与されていないこと、scope_blocked_by_membershipはユーザーの役割がより限定されていること、scope_blocked_by_entitlementは必要なWhite Label権利が有効でないことを意味します。

2つのスコープ層：OAuthとAPIスコープ

OAuthは6つの従来型便利バンドル、すべての詳細なAPIスコープ、公開範囲だけを制御するtools:*セレクターをサポートします。従来型バンドルは次のとおりです。

従来型OAuthバンドルは、それぞれdomains:readやdrive:account:writeなどの詳細なAPIスコープに展開されます。新しい統合はこれらを直接要求できます。White Labelスコープは古いmail:*バンドルから意図的に除外されているため、既存のコネクターがアップグレード後に販売代理店管理権限を得ることはありません。必要なWhite Labelスコープを明示的に要求する必要があります。tools:white_labelセレクターはMCPでの公開を制限しますが、それ自体はAPI権限を付与しません。

3つの接続方法と機能の付与方法

エージェントまたは統合がTrekMailに接続する方法は3つあり、ゲートの仕組みは方法ごとに異なります。MCPの「機能フラグ」（TREKMAIL_ALLOW_DESTRUCTIVE、TREKMAIL_ALLOW_SENDING、TREKMAIL_ALLOW_MIGRATION）は、そのうち1つにしか存在しないため重要です。

要約すると、ホスト型HTTP MCPはOAuth認証情報から公開ツールを絞り込み、stdio MCPはトークンスコープとツールセット、読み取り専用モード、ローカル安全制御の共通部分を使い、REST APIはトークンが持つ詳細なスコープによって直接制限されます。すべてのモードで、実行時のAPI認可が最終的な決定権を持ちます。

スコープ一覧

アカウントと請求

billing:autopayは資金を移動する唯一のスコープなので、内容をよく確認してください。

このスコープはbilling:readから意図的に分離されています。請求書を見ることができる接続に、 請求額を増やす権限を与えるべきではなく、請求の読み取り専用権限は支出への同意ではありません。このスコープが 自動的に含まれることはなく、明示的に付与したトークンまたは接続だけが持ちます。また、 古い粗粒度スコープバンドルには一切含まれないため、このスコープが存在する前に承認された接続は 支出できません。

許可される操作は、メール検証クレジットの購入とサブスクリプションの開始です。既存のサブスクリプションの キャンセル、ダウングレード、変更は一切許可されません。それらの操作に対応する エンドポイントはありません。スコープを持つ接続数に関係なく、アカウント全体で 購入ごと、1日ごと、1か月ごとの支出上限も適用されます。

検証クレジットはNanoを含むすべてのプランで販売されるため、このスコープもすべてのプランで利用できます。

ドメイン

ドメインエイリアス配信はStarterから利用できます。Starterトークンは保存済み状態と現在の状態を読み取れますが、API/MCPによる接続、変更、削除にはPro/Agencyのdomains:write機能が必要です。Starterでもダッシュボードから変更できます。APIとMCPによるドメインエイリアスを参照してください。

White Label

これらの運用トークンスコープは、White Labelの試用または有料アドオンが有効な間だけ表示されます。キャンセル後の猶予期間中は所有者が読み取りスコープを維持しますが、委任されたメンバーとすべての書き込みスコープは削除されます。

現在のメンバーシップも別の上限となります。クライアントやチームメンバーが、より広いトークンを作成して自分の役割、ドメインアクセス、カスタム権限を拡張することはできません。APIとMCPによるWhite Labelチームの管理を参照してください。

メールボックス

メッセージ（メッセージトークン）

メッセージスコープは運用トークン（tm_live_プレフィックス）ではなく、メッセージトークン（tm_msg_プレフィックス）が保持します。メッセージトークンは、mailboxes:message-tokens:manageスコープを持つ運用トークンを使ってAPI経由で作成します。通常の送信経路の制限に加えてAPI固有の保護があります。既定では、トークンごとに1分あたり30件、1日あたり5,000件の読み取り成功が許可されます。送信はトークンごとに1分あたり60件、メールボックス全体で1日あたり100件のAPI送信が許可されます。2つ目のトークン安全カウンターは既定で1日500件のため、通常は低い方のメールボックス上限が優先されます。

すべての新しいWebメールAPIエンドポイント（連絡先、カレンダー、アイデンティティ、テンプレート、ブロック済み送信者、下書き、予約送信、フォルダー、添付ファイル）は既存の3つのメッセージスコープに対応し、新しいスコープは追加されていません。既存のトークンは変更せずに動作し続けます。

messages:readは書き込みアクセスを付与しません。ホスト型OAuthで、より広いmessages:send機能を承認すると、読み取り、書き込み、送信アクセスがまとめて設定されます。手動作成したtm_msg_トークンは、作成時に選択したスコープだけを保持します。

サポートチケット

Starter： APIでは読み取り専用です。ダッシュボードからチケットを作成して返信してください。

SMTP設定

SMTPはドメインごとに設定され（/api/v1/domains/{id}/smtp）、1つのアカウント全体の既定値（/api/v1/smtp/default）が新しいドメインの初期設定を決定します。エンドポイントの全一覧はAPIの概要を参照してください。従来のアカウントレベルの/api/v1/smtpエンドポイントは互換性のために応答しますが、ルーティングは制御しません。

移行

移行スコープは運用トークン（tm_live_プレフィックス）が保持します。StarterはAPIで移行を表示し、ダッシュボードから実行できます。ProとAgencyはAPIとMCP経由で移行を開始、キャンセル、再試行、削除できます。

Cloudflare

Drive

Driveスコープは運用トークン用のスコープです。トークンを選択したメールボックスに限定でき、Driveはそのトークンから他のメールボックススペースを隠します。Driveアドオンの購入、容量変更、キャンセルはAPI/MCPの書き込み操作ではなく、請求変更はダッシュボードで行います。

Nano + Driveアドオン： 有効なDrive Storageアドオンがある場合、Nanoは完全なDriveスコープセットを取得します。それ以外は解放されず、DriveとNanoがすでに持つメール検証スコープだけです。アドオンをキャンセルすると、7日間の猶予期間中は読み取りスコープが有効なため、ダウンロードや移行を完了できます。書き込み、共有、完全削除はすぐに停止します。

メール検証

メール検証スコープはNanoを含むすべてのプランで利用できます。唯一の制限はクレジット残高です。エンドポイントの全リファレンスはメール検証APIを参照してください。

プランのアクセスレベル

White Labelスコープは追加機能であり、基本のProまたはAgencyプランには含まれません。White Label権利が有効な間だけ対象アカウントに表示されます。

ダウングレード時の動作

ProからStarterにダウングレードしても、書き込みスコープを持つ既存トークンは削除されません。代わりに、APIは許可されないスコープを使用するリクエストを実行時にブロックします。

たとえば、Starterプランでmailboxes:createを持つトークンがメールボックスを作成しようとすると、コードtoken_scope_blocked_by_planを含む403が返されます。同じトークンの読み取りスコープは引き続き機能します。

解決するには、古いトークンを取り消し、現在のプランで許可されるスコープだけを含む新しいトークンを作成します。

危険なスコープ

mailboxes:delete、domains:delete、migrations:write、cloudflare:deleteスコープは、ダッシュボードで危険と表示されます。これらのスコープを持つトークンは、メールボックスやドメインの削除を開始したり、Cloudflareトークンを削除したり、その他の不可逆な操作を実行できます。用途に本当に必要か検討してください。

ローカルでホストするMCPサーバーでは、削除ツールを利用可能にする条件として管理者がTREKMAIL_ALLOW_DESTRUCTIVE=trueを要求できます。ホスト型MCPはOAuthで承認されたスコープを使用します。

messages:sendスコープは、メールボックスから実際のメールを送信できます。ローカルでホストするMCPサーバーでは、送信のたびにTREKMAIL_ALLOW_SENDING=trueとconfirm_send=trueが必要な場合もあります。詳細は安全対策と削除インテントを参照してください。

migrations:writeスコープは、保存済み認証情報を使って外部IMAPサーバーに接続するメール移行を開始できます。ローカルでホストするMCPサーバーでは、移行書き込みにTREKMAIL_ALLOW_MIGRATION=trueと呼び出しごとの確認パラメーター（confirm_start、confirm_cancel、confirm_retry）が必要な場合もあります。

ドメイン制約

スコープはトークンが何を実行できるかを制御します。ドメイン制約はどこで実行できるかを制御します。

特定のドメインに限定されたトークンは、そのドメイン内のリソースだけを表示、変更できます。ほかのドメインを公開せずに、業務委託先やエージェントへ1つのクライアントドメインへのアクセスを提供する場合に便利です。

スコープ確認はドメイン制約の確認より先に行われます。必要なスコープがトークンにない場合、ドメイン制約に関係なくリクエストは403で失敗します。

クイック修正

• 403「insufficient_scope」： トークンにこのエンドポイントが必要とするスコープがありません。正しいスコープを持つ新しいトークンを作成してください。
• 403「token_scope_blocked_by_plan」： プランでトークンの1つ以上のスコープが許可されなくなりました。プランをアップグレードするか、トークンを取り消して許可済みスコープで新しいトークンを作成してください。
• 403「scope_blocked_by_entitlement」： White Labelが無効であるか、キャンセル猶予期間中に書き込みが試行されました。接続を再承認する前に再有効化してください。
• 403「scope_blocked_by_membership」： 現在のメンバー役割またはカスタム権限では操作が許可されません。アカウント所有者にメンバーシップの変更を依頼してください。
• 作成フォームに一部のスコープが表示されない： プランがそれらのスコープに対応していません。許可されたスコープだけが表示されます。