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

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

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

利用できる機能

完全な MCP カタログには、現在 stdio 経由の 261 ツールと、ホスト型 HTTP 経由で最大 260 ツールが含まれます。ホワイトラベルでは 20 のツールが追加されます。ブランディング用が七つ、アカウント、メンバー、アクティビティ管理用が 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 として返されるため、別のテナントやクライアントの存在は明らかになりません。

MCP ツール

招待ツールをセルフホスト型 stdio MCP で使用するには、TREKMAIL_ALLOW_SENDING=true が必要です。アクセス変更ツールには TREKMAIL_ALLOW_DESTRUCTIVE=true が必要で、削除にはさらに confirm_remove=true が必要です。これらのスイッチはローカルの安全管理であり、追加の 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. 変更の監査記録が必要な場合は、ホワイトラベルアクティビティを確認します。

対処方法を示すエラー