APIによるメール移行の管理ガイド

Migration APIを使うと、統合やエージェントを通じて任意のIMAPプロバイダーからTrekMailメールボックスへメールをインポートできます。接続のテスト、インポートの開始、フォルダーごとの進行状況の監視、実行中ジョブのキャンセル、失敗したジョブの再試行、古いレコードの削除が可能です。

始める前に

• Starter以上のプランが必要です。Nanoプランには移行ツールが含まれません。
• ProとAgencyでは、APIを介して移行の開始、キャンセル、再試行、削除ができます（migrations:read + migrations:write）。StarterではAPIから移行を読み取り、ダッシュボードから新しい移行を実行できます。
• 一つのアカウントで同時に実行できる移行は一件だけです。現在の移行が完了してから新しい移行を開始するか、先に現在の移行をキャンセルしてください。

スコープ

エンドポイント

接続をテストする

POST /api/v1/migrations/test-connection
Scope: migrations:write

IMAP認証情報を検証し、メッセージ数を含む移行元フォルダーの一覧を返します。移行を開始する前にこれを使用して接続を確認し、インポートするフォルダーをユーザーが選べるようにしてください。

リクエスト本文：

レスポンス（成功）：

{
  "success": true,
  "folders": {
    "INBOX": 1234,
    "Sent": 567,
    "Drafts": 12,
    "Work": 89
  }
}

レスポンス（失敗）： 422。エラーコードはconnection_failedです。

移行の一覧を取得する

GET /api/v1/migrations
Scope: migrations:read

アカウントの移行ジョブをページ分割した一覧で返します。

クエリパラメーター：

移行を取得する

GET /api/v1/migrations/{id}
Scope: migrations:read

フォルダーごとの進行状況を含む、移行の詳細な状態を返します。

レスポンス：

{
  "data": {
    "id": 5,
    "mailbox_id": 10,
    "mailbox_email": "support@acme.com",
    "provider": "gmail",
    "source_host": "imap.gmail.com",
    "source_email": "j***e@gmail.com",
    "status": "processing",
    "progress": 45,
    "total_messages": 1234,
    "imported_messages": 556,
    "failed_messages": 2,
    "skipped_duplicates": 12,
    "selected_folders": ["INBOX", "Sent"],
    "import_since": "2025-01-01",
    "skip_duplicates": true,
    "folders": [
      { "name": "INBOX", "status": "processing", "expected": 1000, "imported": 450, "failed": 2, "skipped": 10 },
      { "name": "Sent", "status": "pending", "expected": 234, "imported": 0, "failed": 0, "skipped": 0 }
    ],
    "error_message": null,
    "poll_hint_seconds": 10,
    "started_at": "2026-03-13T10:00:00+00:00",
    "finished_at": null,
    "created_at": "2026-03-13T09:59:50+00:00"
  }
}

**poll_hint_seconds**は更新をポーリングする頻度を示します。pending/validating/planningでは5秒、processingでは10秒、終了状態ではnullです。

**source_email**はセキュリティのためマスクされます（例：j***e@gmail.com）。

移行を開始する

POST /api/v1/migrations
Scope: migrations:write

新しいメール移行を開始します。一つのアカウントで同時に実行できる移行は一件だけです。

リクエスト本文：

レスポンス： 移行ジョブのリソースを含む201。

エラーレスポンス：

移行をキャンセルする

POST /api/v1/migrations/{id}:cancel
Scope: migrations:write

実行中の移行をキャンセルします。移行は有効な状態（pending、validating、planning、processingのいずれか）である必要があります。

移行を再試行する

POST /api/v1/migrations/{id}:retry
Scope: migrations:write

failedまたはcancelledの移行を再試行します。進行状況を0にリセットし、検証パイプラインに再度入ります。

アカウントで別の移行がすでに実行中の場合は409を返します。

部分的な移行

安全に実行できる場合、TrekMailは部分的に完了した移行の続行を試みることがあります。操作する前に移行状態を確認してください。進行が止まっている場合は移行元アカウントの認証情報と上限を確認し、再試行エンドポイントまたはダッシュボードの続行操作を使用します。最終状態を確認せずに、部分的なインポートが完了すると想定しないでください。

移行を削除する

DELETE /api/v1/migrations/{id}
Scope: migrations:write

移行レコードを削除します。移行が実行中であってはなりません（先にキャンセルしてください）。

成功すると204 No Contentを返します。

レート制限

移行の書き込み操作には、標準のAPIレート制限とは別に、トークンごとに一分あたり10リクエストという専用レート制限があります。

さらに、サーバーはグローバル同時実行数制限（デフォルト：同時移行20件）を適用します。上限に達すると、新しい移行リクエストは503を返し、migration_capacity_reachedとretryable: trueを含みます。数分待ってから再試行してください。

監査イベント

移行APIのすべての操作は監査ログに記録されます。

• migration_started：新しい移行が開始された
• migration_cancelled：実行中の移行がキャンセルされた
• migration_retried：失敗またはキャンセルされた移行が再試行された
• migration_deleted：移行レコードが削除された

MCPツール

同じ移行機能をMCPサーバーから利用できます。単一移行と一括移行に対するテスト、一覧表示、開始、キャンセル、再試行、再開、パスワード更新、削除の操作が含まれます。ローカルでホストするMCPの管理者は、移行の書き込みに明示的な承認を要求できます。詳しくはAIエージェントの接続（MCP）を参照してください。

一括移行API

一括移行APIを使うと、CSV形式のデータペイロードで多数のアカウントを一度に移行できます。ユーザーガイドについてはメールの一括移行、データ形式については一括移行CSV形式を参照してください。

エンドポイント

プレビューリクエスト

POST /api/v1/migrations/bulk/preview
Scope: migrations:write

レスポンスには、分類された行（valid、invalid_source_email、invalid_destinationなど）、プラン上限、推定時間、ストレージ情報が含まれます。

バッチ開始リクエスト

POST /api/v1/migrations/bulk
Scope: migrations:write

プレビューと同じフィールドに、次の項目が加わります。

同時実行数の上限

サーバー全体の上限（同時移行20件）は、単一移行と一括移行で共有されます。

MCPツール

一括移行用MCPツールは、preview_bulk_migration、start_bulk_migration、list_bulk_migrations、get_bulk_migration、cancel_bulk_migration、retry_bulk_migration、resume_bulk_migration、delete_bulk_migration、update_bulk_migration_job_passwordです。ローカルでホストするMCPの管理者は、書き込み操作に明示的な承認を要求できます。

クイック修正

• 403 "insufficient_scope"： トークンにはmigrations:readまたはmigrations:writeが必要です。正しいスコープを持つ新しいトークンを作成してください。
• 403 "token_scope_blocked_by_plan"： 移行スコープには有料プラン（Starter以上）が必要です。
• 409 "active migration running"： 既存の移行をキャンセルするか、完了するまで待ってください。
• 503 "migration_capacity_reached"： サーバーが上限に達しています。数分後に再試行してください。
• test-connectionで422： IMAP認証情報、ホスト名、ポート、セキュリティ設定を確認してください。