通过 API 管理电子邮件迁移

迁移 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。

速率限制

迁移写入操作有专用速率限制：每个令牌每分钟 10 个请求，与标准 API 速率限制分开计算。

此外，服务器会实施全局并发限制（默认：同时运行 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 凭据、主机名、端口和安全设置。