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

Claude の TrekMail を開き、Connect を選択してログインし、アクセスを許可します。API トークンの作成は不要です。AI Agents & API → Tokens → Connected apps で権限の確認や接続解除ができます。

独自の White Label ブランド： ブランドのダッシュボードに表示される MCP アドレスとブランド名を使用し、custom connector として追加してください。公開 TrekMail ページは TrekMail でログインするため、独自ブランドの接続を置き換えるものではありません。

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

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

1つのキーでメールを読む

Pro と Agency では、API キーの作成時に「メールを読む」を選びます。明示的な権限は mailboxes:messages:read です。mailboxes:read はアドレスと接続設定のみを表示します。すべてのメールボックスを選ぶと現在と将来のボックスを含みます。特定のドメインとボックスにも制限できます。既存キーに新しい権限は自動追加されません。

以下の GET ルートにアカウントキーを使用します。送信、削除、変更には別のメールトークンと権限が必要です。ホスト型 MCP は OAuth のみを受け付け、tm_live_ や tm_msg_ は使用できません。トークンの種類のエラーで、正しいルートや認証方法がエージェントに示されます。

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

アプリ権限の選択と編集

API キーや接続済みアプリの詳細から「アクセスを編集」を選び、変更を確認して確定します。API キーの秘密値は変わりません。権限、対象、期間を減らすと既存のボックストークンも制限され、未開始の送信が取り消されます。新しい OAuth 接続はすぐに制限でき、拡大には再承認が必要です。以前の接続を編集すると切断され、再接続用の選択が保存されます。メールトークンでは権限の削除と期間の短縮のみ可能です。

始める前に

• 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スコープとプランの権限を参照してください。

ドメイン制限

既定では、トークンはアカウント上のすべてのドメインにアクセスでき、後から追加したドメインも含まれます。範囲を狭める方法は 2 つあります。

• 選択したドメインのみ: トークンは選択したドメインだけにアクセスできます。後から追加したドメインは、トークンを編集して選択するまで対象外です。
• 指定したドメインを除くすべてのドメイン（現在および今後）: トークンは選択したドメイン以外のすべてのドメインにアクセスでき、後から追加したドメインも含まれます。ドメインを追加するたびにトークンを編集しなくても、特定の顧客のメールにエージェントを近づけないようにできます。

制限されたトークンが他のドメインのリソースにアクセスしようとすると 404 が返されます。APIは、そのドメインが存在しないものとして動作します。どちらの場合も、範囲外のドメインに影響するアカウント全体の設定（新しいメールボックスの既定値など）は変更できません。

一部のドメインに限定されたチームメンバーの場合、「除く」は、そのメンバーのドメインから選択したドメインを除いたものを意味し、後からアカウントに追加されたドメインは含まれません。除外したドメインを削除して再度追加すると新しいドメインとして扱われるため、もう一度除外してください。

トークンを再発行する

シークレットがもう一度必要になったときや、シークレットが漏れた可能性があるときは、トークンを再発行します。トークンの名前、権限、ドメイン、メールボックス、有効期限、監査履歴はそのまま残り、シークレットだけが変わります。

1. AIエージェントとAPI → トークンに移動し、トークンの詳細を開きます。
2. 再発行をクリックします。
3. 旧シークレットが無効になる時期を選びます：今すぐ、1時間後、24時間後、3日後、7日後。旧シークレットがトークン自体の有効期限を超えて使えることはありません。
4. 再発行をクリックし、新しいシークレットをコピーします。新しいトークンと同じく、表示されるのは一度だけです。

旧シークレットが有効な間は、トークンの詳細にいつ無効になるかが表示され、今すぐ無効にするを選べます。それまでに各アプリのシークレットを置き換えてください。その後も旧シークレットを使うリクエストには 401 Unauthorized が返されます。

旧シークレットで作成したメッセージトークン（tm_msg_...）も同時に無効になります。メッセージトークンを自分で作成するアプリは、新しいシークレットで新しいトークンを作成できます。シークレットが漏れた可能性がある場合は今すぐを選んでください。

トークンを取り消す

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を再有効化し、必要なスコープを持つ認証情報を作成または承認してください。
• ロール変更後に委任トークンが停止した: メンバーアクセスの縮小、停止、削除によって、影響を受ける認証情報はすぐに取り消されます。所有者が正しいアクセスを復元した後、新しいトークンを作成してください。