API と MCP でホワイトラベルチームを管理

ホワイトラベルアカウントは、ダッシュボードに戻らずに管理できます。REST API と MCP サーバーは、アカウントのセットアップ状況、クライアントとチームメンバー、ロール、ドメインアクセス、招待、一時停止、削除、復元、クライアントのストレージ上限、アクティビティ履歴に対応しています。ブランディングには、同じホワイトラベルツールセットと専用のブランディングガイドを使用します。

重要な境界は単純です。接続によって、その背後にいるユーザーがすでに持つ権限を超えるアクセスを付与することはできません。特定ドメインに制限されたマネージャーは無関係なドメインへユーザーを招待できず、カスタムロールは呼び出し元が持たない権限を付与できません。

利用できる機能

完全な MCP カタログには、現在 stdio 経由の 284 ツールと、ホスト型 HTTP 経由で最大 283 ツールが含まれます。ホワイトラベルでは 23 のツールが追加されます。ブランディング用が七つ、アカウント、メンバー、アクティビティ管理用が 13、クライアントのストレージ上限用が三つです。

これらのツールは全員に読み込まれるわけではありません。TrekMail は tools/list を構築する前に、アカウントの現在のホワイトラベル利用資格、ユーザーの現在のメンバーシップ、トークンまたは OAuth 許可、ドメイン制約、選択されたツールセット、ローカルの安全設定を評価します。ホワイトラベルへのアクセス権がない接続には、スキーマ自体が提供されません。

利用資格の状態

ホワイトラベルの読み取りアクセスがある場合、GET /api/v1/white-label または get_white_label ツールを呼び出すと、active と読み取り専用の grace を区別し、セットアップの進捗と猶予期限を確認できます。利用できないアカウントはそのエンドポイントを呼び出せません。保存済みの認証情報に、そのアカウントでは使用できなくなったホワイトラベルスコープが残っている場合、API は scope_blocked_by_entitlement を返し、再有効化する場所を示します。

スコープ

メンバーアクティビティのエンドポイントには activity:read と members:read の両方が必要です。レスポンスにアクティビティだけでなくメンバーレコードも含まれるためです。ホスト型 OAuth 接続は、tools:white_label セレクターを使ってこのツールファミリーを要求します。有効な REST スコープは、引き続きアカウントとメンバーシップによって制限されます。

セルフホスト型 MCP サーバーでツールセットの許可リストを使用する場合は、TREKMAIL_TOOLSETS に white_label を追加します。書き込みツールには、後述するローカルの安全ゲートも適用されます。

REST エンドポイント

すべてのパスは https://trekmail.net/api/v1 の配下にあります。

この表の書き込みには、すべて Idempotency-Key ヘッダーが必要です。同じキーで同じリクエストを繰り返すと、最初の安全な結果が返されます。招待トークンなど、再実行に含まれる一度限りの機密情報は伏せられます。同じキーを異なる本文で再利用すると idempotency_mismatch が返されます。

最初にアクセスカタログを読み取る

ロールの権限を連携処理にハードコードしないでください。招待またはアクセス変更の前にアクセスカタログを呼び出します。その grantable フラグは呼び出し元の現在のメンバーシップを反映し、オーナーがそのメンバーシップを調整すると変わる場合があります。

現在、新しい招待で提供されるロールは次のとおりです。

• client - 割り当てられたドメインとメールボックスを管理しますが、リセラーと TrekMail の非公開な関係は表示されません。
• webmail_only - チームリストには表示されますが、ダッシュボード権限は付与されません。
• domain_admin - 割り当てられたドメインとその DNS を管理しますが、メールボックスは管理しません。
• mailbox_operator - 割り当てられたドメイン内のメールボックスを管理しますが、ドメイン自体は管理しません。
• read_only - 許可されたアカウント領域を確認できますが、変更はできません。
• custom - permissions に記載された権限だけを受け取ります。

一部のロールでは明示的な domain_ids が必要です。それ以外のロールでは all_domains を使用できます。適用されるルールはアクセスカタログで確認できます。呼び出し元がより広いロール、権限、ドメインセットを付与しようとすると、TrekMail は招待を暗黙に狭めるのではなく scope_blocked_by_membership を返します。

クライアントを招待する

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

レスポンスには、メンバー、メール送信が成功したかどうか、一度限りの招待 URL が含まれます。配信に問題があっても招待は消去されません。オーナーは URL をコピーするか、後で再送信できます。

カスタムロールの場合は、アクセスカタログから grantable_permissions を読み取り、選択した値を permissions で送信します。少なくとも一つの権限が必要です。

メンバーの状態を追跡する

すべてのメンバーレスポンスに allowed_operations が含まれます。推測せず、このリストを使用してください。

• 保留中の招待は、更新、一時停止、再送信、削除が可能です。
• 有効なメンバーは、更新、一時停止、削除が可能です。
• 一時停止中のメンバーは、更新、再開、削除が可能です。
• 削除済みのメンバーは復元できます。
• オーナーの行は参考情報として表示されますが、これらのエンドポイントでは変更できません。

このリストは、現在の呼び出し元に応じても絞り込まれます。読み取り専用の接続、呼び出し元自身のメンバーシップ、呼び出し元が管理できる範囲より広い権限を持つメンバーでは空になります。

呼び出し元は自分自身を削除または一時停止できません。また、委任された呼び出し元は、自分より広いアクセス権を持つメンバーを管理できません。無効な状態遷移では membership_state_conflict が返され、メンバーを再度読み取るよう案内されます。

ユーザーを一時停止または削除すると、そのメンバーシップで作成された API キーとメールボックスキーが無効化されます。メンバーシップを再開または復元しても、古いキーは戻りません。そのユーザーは再接続するか、新しい認証情報を作成する必要があります。

アクティビティとプライバシーの境界

GET /white-label/activity は、招待、ロールとドメインの変更、一時停止、削除、復元、関連するセキュリティ操作を返します。action、member_id、per_page で絞り込めます。

GET /white-label/members/{id}/activity は、そのメンバーのアカウント操作と最近のサインインをまとめて返します。これには、時刻、IP アドレス、おおよその場所、ブラウザー、オペレーティングシステム、デバイスの種類が含まれます。このルートは意図的に両方の読み取りスコープを要求します。ドメイン制約のある呼び出し元が要求できるのは、そのドメイン境界に完全に含まれるメンバーだけです。アクセスできないメンバーは 404 として返されるため、別のテナントやクライアントの存在は明らかになりません。

クライアントのストレージ上限

クライアントのストレージ上限は、クライアントのドメインに、メールボックスと Drive で使う容量を MB 単位でひとつ割り当てます。ダッシュボードでの使い方は、クライアントごとに個別のストレージ上限を設定するをご覧ください。 チームの誰もそのドメインを持っていない上限（クライアントを招待する前にここで作成したものなど）は、チームとクライアントページのクライアントのいないストレージ上限に表示されます。

• 読み取りには members:read が必要です。一部のドメインに限定された呼び出し元には、すべてのドメインが自分のものである上限だけが表示されます。別のクライアントの上限や、自分の範囲外のドメインも含む上限は一覧に含まれず、存在しない ID と同じく 404 が返ります。
• 変更には members:write と、アカウントのすべてのドメインにアクセスできる呼び出し元が必要です。一部のドメインに限定されたメンバーには 403 scope_blocked_by_membership、一部のドメインに限定されたキーには 403 token_resource_constrained が返ります。
• POST は「チームとクライアント」ページと同じように動作します。上限のないドメインには新しい上限が作成されます（201）。ドメインがすでにひとつの上限を共有している場合はその上限が変更され、指定したドメインのうち上限のないものがそこに加わります（200）。
• PATCH は storage_limit_mb、domain_ids、またはその両方を受け付けます。domain_ids はドメインのセット全体を置き換え、含まれなかったドメインはアカウントのストレージに戻ります。
• 各上限は storage_limit_mb、domain_ids、allocated_mb（メールボックスの固定サイズ）、pending_invites_mb（未完了の招待の固定サイズ）、pool_mb（共有ストレージのメールボックスが分け合う容量）、used_bytes、member_ids を返します。

各メンバーのレコードには client_limit が含まれます。メンバーのすべてのドメインが属するひとつの上限で、id、storage_limit_mb、allocated_mb、used_bytes を持ちます。該当する上限がなければ null です。一部のドメインに限定された呼び出し元に対しては、その上限が呼び出し元の範囲外のドメインも含む場合も null になります。

メールボックス自体のサイズは PATCH /mailboxes/{id}/storage（mailboxes:write）または set_mailbox_storage ツールで設定します。詳しくは REST API の概要をご覧ください。

MCP ツール

招待ツールをセルフホスト型 stdio MCP で使用するには、TREKMAIL_ALLOW_SENDING=true が必要です。アクセス変更ツールとクライアントのストレージ上限のツールには TREKMAIL_ALLOW_DESTRUCTIVE=true が必要で、メンバーや上限の削除にはさらに confirm_remove=true が必要です。ホワイトラベルのツールセットに含まれない set_mailbox_storage にも同じ条件があります。これらのスイッチはローカルの安全管理であり、追加の API 権限ではありません。ホスト型 MCP には、承認済みの独自の安全ポリシーが適用されます。

独自のキーを指定しなかった場合、ツールは決定的な冪等キーを作成します。ワークフローが別のプロセスで再起動する可能性がある場合は、独自の idempotency_key を指定すると便利です。

安全な自動化フロー

1. get_white_label を呼び出します。scope_blocked_by_entitlement の場合は停止します。成功した grace レスポンスでは、読み取り操作だけを続行します。
2. アクセスを付与する直前に get_white_label_access_catalog を呼び出します。
3. 対象メンバーを変更する前に、一覧表示または読み取りを行います。
4. allowed_operations、目的のロール、権限、ドメイン ID を確認します。
5. 書き込みには安定した冪等キーを使用します。
6. メンバーを再度読み取り、結果のステータスと有効な権限を報告します。
7. 変更の監査記録が必要な場合は、ホワイトラベルアクティビティを確認します。

対処方法を示すエラー