TrekMail APIトークンの作成と管理

APIトークンは、アプリケーションやエージェントがアカウントで実行できる操作を制御します。各トークンには、名前、スコープ、任意のドメイン制限、有効期限があります。

MCPクライアントを接続しますか？ ブラウザー認証に対応している場合は、https://trekmail.net/mcp をリモートMCPサーバーとして追加し、ブラウザーでアクセスを承認します。通常、トークンの作成や貼り付けは不要です。手動の tm_live_ トークンは、スクリプト、CIジョブ、セルフホストMCP、このフローに対応しないクライアント向けです。AIエージェントを接続する (MCP)を参照してください。

始める前に

• Nanoを含むすべてのプランでAPIトークンを作成できます。NanoプランはEmail Verifierスコープ (verify:read、verify:write) のみに制限されます。
• Starterプランでは、読み取り専用のインフラストラクチャスコープに加え、DriveとEmail Verifierのすべてのスコープを利用できます。Starterでもダッシュボードから転送を管理できますが、APIによる転送への書き込み (mailboxes:forwarding:write) にはProまたはAgencyが必要です。ProとAgencyではすべてのスコープが利用できます。
• 所有者はアカウントのすべての認証情報を管理できます。APIトークン権限を持つ委任メンバーは、自分が作成した認証情報だけを管理でき、メンバーシップにすでに含まれるスコープとドメインだけを付与できます。
• ヒント： AIエージェントとAPIのページでツアーを開始をクリックすると、接続方法、トークン、接続済みアプリ、監査ログを簡単に確認できます。

Drive自動化トークンを作成する

Drive APIとMCPツールは操作トークン (tm_live_...) を使用します。ワークフローに必要なDriveスコープだけを選択してください。

• 読み取り専用レポート: drive:account:read、drive:mailbox:read、drive:addon:read のいずれか。
• アップロード自動化: drive:account:write または drive:mailbox:write を追加。
• 公開配信リンク: drive:account:share または drive:mailbox:share を追加。
• 完全削除: drive:account:purge または drive:mailbox:purge は、厳格に管理された別のトークンでのみ使用。

Drive Add-onの購入、容量変更、解約はAPIトークンでは実行できません。エージェントは drive:addon:read でAdd-onの状態と料金を読み取れますが、サブスクリプションの変更はダッシュボードで行います。

White Label自動化トークンを作成する

White Labelは、branding:read、branding:write、members:read、members:write、activity:read という五つの操作トークンスコープを使用します。アカウントにWhite Labelアクセスがある間だけ表示されます。members:write は、アクセスを削除し、他の人のキーを取り消せるため、危険なスコープとして表示されます。

読み取り専用の状態確認と監査の統合には、branding:read、members:read、activity:read を選択します。branding:write はブランドとDNSの設定にのみ追加します。members:write は、自動化で人を招待または変更する必要がある場合にのみ追加します。

解約猶予期間中、所有者は復旧用の三つの読み取りスコープを保持しますが、書き込みと委任されたWhite Label認証情報は動作しなくなります。再有効化しても、取り消された認証情報は復活しません。新しい認証情報を作成または承認してください。

トークンを作成する

1. AIエージェントとAPI → トークンに移動します。
2. トークンを作成をクリックします。
3. フォームに入力します。
   • 名前: トークンを識別するラベル。例:「Claudeエージェント」、「CI/CDパイプライン」。
   • 有効期限: 7日、30日、90日、指定日、無期限から選択します。
   • スコープ: トークンが実行できる操作を選択します。許可されているすべてのスコープが既定で選択されています。
   • ドメイン制限: 「すべてのドメイン」を選択するか、特定のドメインを選んでアクセスを制限します。
4. トークンを作成をクリックします。

作成後、平文トークンは一度だけ表示されます。すぐにコピーするか、ダウンロードボタンで .txt ファイルとして保存してください。

トークンを再表示することはできません。 確認画面を閉じる前に安全に保存してください。

メッセージトークンを作成する

メッセージトークンを使うと、エージェントは特定のメールボックスからメールを読み取り、送信できます。操作トークンとは別のもので、操作トークンを使ってAPIからプログラムで作成します。

メッセージトークンを作成するには、エージェントが次を呼び出します。

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

ワークフローに必要な最小限のスコープを選択します。

平文トークン (tm_msg_...) は一度だけ返されます。MCP設定に TREKMAIL_MESSAGE_TOKEN として追加してください。

メッセージトークンは ProとAgency プランで利用できます。操作トークンには mailboxes:message-tokens:manage スコープが必要です。

接続済みのGmailや他の外部受信トレイには external_account_id を使用します。受信者に承認済みのビジネスアドレスを表示するには、ID endpointから返された identity_id も使用します。APIとMCPで差出人アドレスを使うを参照してください。

トークンの形式

TrekMailは、トークンの種類を区別するために二つのプレフィックスを使用します。

プレフィックスの後の最初の8文字は、識別しやすいようにダッシュボードに表示可能なプレフィックスとして保存されます。

スコープ

スコープは、トークンが実行できる操作を制御します。選択できる項目はプランによって異なります。

• Nano: Email Verifier (verify:read、verify:write) のみ。Drive Storageを追加すると、アカウントには利用資格のあるDrive APIとMCP機能も付与されます。
• Starter: DriveとEmail Verifierへの完全なアクセス、およびその他すべて（ドメイン、メールボックス、転送、メールフィルター、自動返信、移行、チケット、SMTP、Cloudflare）への読み取り専用アクセス。移行の作成、チケットへの返信、自動返信の変更など、StarterがAPIで公開していない書き込み操作にはダッシュボードを使います。
• ProとAgency: 完全なアクセス。すべての機能群で読み取り、書き込み、作成、削除ができ、APIによるメールの読み取りと送信用のメッセージトークンも利用できます。

White LabelスコープはAdd-onの利用資格であり、プラン表を迂回するものではありません。White Labelが有効な場合にのみ提供され、解約猶予期間中は所有者が読み取り専用の復旧アクセスを保持します。

各スコープについては、APIスコープとプランの権限を参照してください。

ドメイン制限

既定では、トークンはアカウント上のすべてのドメインにアクセスできます。特定のドメインに制限するには、次の操作を行います。

1. ドメイン制限セクションで選択したドメインを選びます。
2. トークンがアクセスするドメインを選択します。

制限されたトークンが他のドメインのリソースにアクセスしようとすると 404 が返されます。APIは、そのドメインが存在しないものとして動作します。

トークンを取り消す

1. AIエージェントとAPI → トークンに移動します。
2. 一覧からトークンを探します。
3. 取り消すをクリックします。
4. 取り消しを確認します。

取り消されたトークンはすぐに動作を停止します。取り消されたトークンを使うAPIリクエストには 401 Unauthorized が返されます。

取り消しは永続的で、元に戻せません。アクセスを復元する必要がある場合は新しいトークンを作成してください。

トークンの状態

トークンには三つの状態があります。

トークンページの状態フィルターを使い、状態別にトークンを表示できます。

監査記録

トークンの作成と取り消しはすべて監査ログタブに記録されます。イベントにはトークン名、操作、時刻が含まれます。

簡単な解決方法

• 「このプランではスコープを利用できません」: プランにそのスコープが含まれていません。Nanoは verify:read と verify:write のみです（Drive Storage Add-onを追加すると drive:* スコープも利用できます）。Starterではすべてのインフラストラクチャ機能群の読み取りに加え、DriveとEmail Verifierを完全に利用できます。ProとAgencyではすべての書き込みが利用できます。
• 平文トークンを紛失した: トークンは復元できません。取り消して新しいものを作成してください。
• トークンは動作するが一部のドメインで404を返す: ドメイン制限が設定されている可能性があります。取り消して「すべてのドメイン」で再作成するか、不足しているドメインを制限に追加してください。
• White Labelスコープが scope_blocked_by_entitlement を返す: White Labelを再有効化し、必要なスコープを持つ認証情報を作成または承認してください。
• ロール変更後に委任トークンが停止した: メンバーアクセスの縮小、停止、削除によって、影響を受ける認証情報はすぐに取り消されます。所有者が正しいアクセスを復元した後、新しいトークンを作成してください。