APIの安全対策と削除インテントのガイド

TrekMail APIは、誤操作によるデータ損失を防ぐように設計されています。破壊的な操作には複数の確認手順が必要です。レート制限によって一括操作のミスを防ぎ、すべての操作を記録します。

ごみ箱。 メールボックスの削除インテントを確認すると、すぐに破棄されるのではなく、メールボックスが7日間のごみ箱に移動します。ダッシュボードでは最近削除した項目と表示されます。削除されたメールボックスを一覧表示し、期間内に復元できます。

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

保持期間が過ぎると、日次ジョブによってごみ箱内のメールボックスが完全に削除されます。復元時には、ドメインごとのメールボックス上限が再確認されます。MCPエージェントはrestore_mailboxツールとlist_trashed_mailboxesツールを使用します。confirm_delete_intentは復元可能な操作となり、不可逆な操作ではありません。ドメインまたはアカウントを削除すると、そのメールボックスは完全に削除され、ごみ箱は使用されません。

2段階の削除（削除インテント）

メールボックスとドメインの削除は、APIで最も影響の大きい破壊的操作です。2段階の手順が使用されます。

ステップ1：削除インテントを作成する

POST /api/v1/mailboxes/{id}:delete-intent

削除される内容を示す、有効期限付きのインテントが作成されます。レスポンスには次の情報が含まれます。

• リスクフラグ：影響を受ける転送ルール、エイリアス、実行中の移行に関する警告。
• 有効期限：インテントは10分後に期限切れになります。その後は新しいインテントを作成する必要があります。
• 確認URL：ステップ2で呼び出すURL。

この段階ではデータは削除されません。

ステップ2：インテントを確認する

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

TrekMailのメールボックスごみ箱が有効な場合、確認するとメールボックスが最近削除した項目に移動し、status: "executed"の完了済みインテントが返されます。復元時にドメインのメールボックス上限に空きがあれば、7日間は復元できます。

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

復元期間が過ぎると、TrekMailの日次クリーンアップによってメールボックスが完全に削除されます。それまでに、ごみ箱の一覧または復元エンドポイントを使用してください。ドメインやアカウントの削除では、このメールボックス復元手順は使用されません。

追加の安全確認として、確認リクエストにはX-Confirm-Delete: trueヘッダーが必要です。

リスクフラグ

削除インテントを作成すると、APIは処理を続行すべきでない可能性を示す条件を確認します。

確認前にこれらのフラグを確認してください。APIはリスクフラグを理由に確認を拒否しません。フラグは情報提供のみを目的としています。

破壊的操作のレート制限

破壊的操作には、通常のAPI分単位レート制限に加えて、2層のレート制限があります。

• トークンごとの1日上限：各トークンが1日に確認できる削除インテント数には上限があります。
• 確認間のクールダウン：1件の削除を確認した後、次の確認が受け付けられるまで短い待機時間があります。

どちらも、制限に達するとRetry-Afterヘッダー付きの429 Too Many Requestsを返します。

ローカルホスト型サーバーのMCP安全制御

stdio MCPサーバーを自分で運用する場合、管理者は削除ツールを利用可能にする条件としてTREKMAIL_ALLOW_DESTRUCTIVE=trueを要求できます。これはローカルの安全制御であり、TrekMail製品の機能スイッチではありません。ホスト型MCPはOAuthで承認された権限を使用します。

読み取りツールは、付与されたスコープ内で引き続き利用できます。削除操作を許可する前に、エージェントのタスクとスコープを確認してください。

冪等性

Idempotency-Keyを必要とする書き込みエンドポイントは、エンドポイント表とOpenAPI仕様にその旨を記載しています。リクエストを再試行する前に、論理操作ごとに新しいキーを使用してください。

Idempotency-Key: create-mailbox-alice-2024

• 同じキーと同じ本文では、操作を繰り返さずに元のレスポンスが再現されます。
• 同じキーと異なる本文では、409 Conflictが返されます。
• 異なるトークンは独立したキースペースを使用します。

MCPサーバーはツール呼び出し用に再試行しても安全な冪等性キーを生成するため、再試行によって完了済みの操作が繰り返されることはありません。

送信の安全ゲート

MCPサーバー経由のメール送信には、破壊的操作のゲートと似た独自の2重安全設計があり、2つの独立した確認を使用します。

ゲート1：ローカルサーバー制御

ローカルでホストするMCPサーバーでは、send_messageツールを許可するためにTREKMAIL_ALLOW_SENDING=trueを設定します。ホスト型MCPはOAuthで承認された権限を使用します。

ゲート2：呼び出しごとの確認

環境ゲートが有効でも、send_messageを呼び出すたびにパラメーターconfirm_send=trueを含める必要があります。含まれていない場合、ツールはエージェントに確認を求めるエラーを返します。

2つのゲートが必要な理由

ローカル制御は、MCPサーバーを設定する管理者が一度設定します。呼び出しごとの制御では、各メールを送信するかどうかをエージェントが能動的に判断する必要があります。片方の制御だけでは不十分であり、メールがサーバーから送信されるには両方を通過する必要があります。

これにより、利用可能なツールの影響を理解せずに調べるエージェントによる誤送信を防ぎます。エージェントはメッセージトークンを使用してメッセージを自由に一覧表示および閲覧できますが、両方の安全ゲートを満たさない限り送信できません。

移行の安全ゲート

MCPサーバー経由のメール移行には、送信や破壊的操作と同様の独自の安全ゲートがあります。

移行のローカルサーバー制御

ローカルでホストするMCPサーバーでは、移行書き込みツール（start_migration、retry_migration、delete_migration）を許可するためにTREKMAIL_ALLOW_MIGRATION=trueを設定します。ホスト型MCPはOAuthで承認された権限を使用します。

cancel_migrationはこの設定に関係なく常に利用できます。制御不能な移行を停止するために必ずアクセス可能でなければならない安全操作です。

読み取り専用の移行ツール（list_migrations、get_migration）はゲートなしで動作します。test_migration_connectionは外部へのIMAP接続を行うため、TREKMAIL_ALLOW_MIGRATION=trueが必要です。

移行の呼び出しごとの確認

各移行書き込みツールには確認パラメーターが必要です。

• start_migrationにはconfirm_start=trueが必要です
• cancel_migrationにはconfirm_cancel=trueが必要です
• retry_migrationにはconfirm_retry=trueが必要です

確認パラメーターがない場合、ツールはエージェントに確認を求めるエラーを返します。

サーバー全体の同時実行上限

APIは同時移行数にグローバル上限を適用します（既定値：20）。上限に達すると、新しい移行リクエストはmigration_capacity_reachedおよびretryable: trueを含む503を返します。多くのアカウントが同時に移行する際に、サーバーリソースを保護します。

監査ログ

データを変更するすべてのAPI操作は監査ログに記録され、ダッシュボードのAIエージェントとAPI → 監査ログで確認できます。イベントには次のものがあります。

• トークンの作成または取り消し：操作トークンを作成または取り消した担当者と日時。
• メッセージトークンの作成または取り消し：メッセージトークンを作成または取り消した担当者。
• インテントの作成：特定のメールボックスに削除インテントが作成されました。
• インテントの確認： 削除リクエストが受け付けられました。
• 削除の実行： メールボックスが最近削除した項目に移動し、復元期間が開始されました。
• インテントの期限切れ：未確認のインテントが10分後に期限切れになりました。
• メールボックスの作成：API経由で新しいメールボックスがプロビジョニングされました。
• 招待の作成：メールボックス設定の招待が送信されました。
• 転送の更新：メールボックスの転送ルールが変更されました。
• DNS再確認の開始：ドメインのDNS検証がリクエストされました。
• 移行の開始：API経由でメール移行が開始されました。
• 移行のキャンセル：実行中の移行がキャンセルされました。
• 移行の再試行：失敗またはキャンセルされた移行が再試行されました。
• 移行の削除：移行レコードが削除されました。
• メッセージの閲覧：メッセージAPI経由でメッセージが一覧表示または閲覧されました。
• メッセージの送信：メッセージAPI経由でメールが送信されました。
• メッセージ送信の失敗：メール送信の試行が失敗しました。
• メッセージフラグの更新：メッセージフラグ（既読/未読、スター）が変更されました。
• メッセージの削除：メールボックスフォルダーからメッセージが削除されました。
• メッセージの移動：メッセージがフォルダー間で移動されました。
• ドメインの作成：API経由でドメインが追加されました。
• ドメインの削除：API経由でドメインが削除されました。
• チケットの作成：API経由でサポートチケットが開かれました。
• チケットへの返信：チケットに返信が投稿されました。
• チケットの終了：チケットが終了されました。
• SMTPの設定：SMTP設定が更新されました。
• SMTP接続の削除：カスタムSMTP接続が削除されました。
• SMTPテストの待機登録：SMTP接続テストが開始されました。
• Cloudflareトークンの削除：保存されていたCloudflareトークンがAPI経由で削除されました。

閲覧、送信、フラグ更新、削除、移動を含むすべてのメッセージAPIイベントが完全に記録されます。監査レコードは90日間保持されます。

各イベントには、使用したトークン、影響を受けたリソース、IPアドレス、リクエストIDが記録されます。

特定のアクティビティを調査するには、イベント種別、トークン、日付範囲で監査ログを絞り込みます。

クイック修正

• 確認前にインテントが期限切れになった： 新しい削除インテントを作成してください。インテントは10分後に期限切れになります。
• 「Missing confirm header」： 確認リクエストにX-Confirm-Delete: trueヘッダーを追加します。
• 削除確認時の429： 1日上限またはクールダウンに達しています。Retry-Afterで指定された期間だけ待ちます。
• セルフホストMCPエージェントが削除ツールは無効と報告する： ローカル管理者は、そのMCPプロセスの環境でTREKMAIL_ALLOW_DESTRUCTIVE=trueを設定できます。
• セルフホストMCPエージェントが「Sending is disabled」と報告する： ローカル管理者は、そのMCPプロセスの環境でTREKMAIL_ALLOW_SENDING=trueを設定できます。
• MCPエージェントが「Send not confirmed」と報告する： エージェントはsend_messageを呼び出すたびにパラメーターconfirm_send=trueを渡す必要があります。
• セルフホストMCPエージェントが移行ツールは無効と報告する： ローカル管理者は、そのMCPプロセスの環境でTREKMAIL_ALLOW_MIGRATION=trueを設定できます。
• 503「migration_capacity_reached」： サーバー全体で実行中の移行が多すぎます。数分待ってから再試行してください。
• 409「active migration running」： 既存の移行をキャンセルするか、完了を待ってから新しい移行を開始してください。