TrekMail 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 现在是可恢复操作，不再不可逆。删除域名或账户会永久删除其邮箱，并且不使用回收站。

两步删除（删除意图）

删除邮箱和删除域名是 API 中影响最大的破坏性操作。它们采用两步流程：

第 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" 的已完成意图。邮箱可以在七天内恢复，前提是恢复时该域名仍有足够的邮箱额度。

{
  "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 每分钟频率限制外，破坏性操作还有两层限制：

• 每个令牌的每日限制：每个令牌每天只能确认有限数量的删除意图。
• 确认之间的冷却时间：确认一次删除后，需要等待一小段时间才能接受下一次确认。

触发任一限制时，都会返回带有 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 服务器发送电子邮件有自己的双重安全门控设计。它类似于破坏性操作的门控，但包含两项独立检查：

门控 1：本地服务器控制

对于本地托管的 MCP 服务器，请设置 TREKMAIL_ALLOW_SENDING=true 以允许 send_message 工具。托管式 MCP 使用 OAuth 期间批准的权限。

门控 2：每次调用确认

即使环境门控已启用，每次调用 send_message 时也必须包含参数 confirm_send=true。如果缺少该参数，工具会返回错误并要求代理确认。

为什么需要两道门控？

本地控制由配置 MCP 服务器的管理员设置一次。每次调用控制则要求代理主动决定是否发送每封电子邮件。任何一道门控单独通过都不够；只有两者都通过后，邮件才能离开服务器。

这可以防止代理在不了解后果的情况下探索可用工具并意外发送邮件。代理可以使用消息令牌自由列出和读取消息，但必须满足两道安全门控才能发送。

迁移安全门控

通过 MCP 服务器迁移电子邮件有自己的安全门控，与发送和破坏性操作的门控类似。

迁移的本地服务器控制

对于本地托管的 MCP 服务器，请设置 TREKMAIL_ALLOW_MIGRATION=true 以允许迁移写入工具（start_migration、retry_migration、delete_migration）。托管式 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）。达到限制后，新的迁移请求会返回 503，并包含 migration_capacity_reached 和 retryable: true。当多个账户同时迁移时，此机制可以保护服务器资源。

审计日志记录

每项会更改数据的 API 操作都会记录在审计日志中，可在控制面板的 AI 代理与 API → 审计日志下查看。事件包括：

• 令牌已创建或撤销：谁在何时创建或撤销了操作令牌。
• 消息令牌已创建或撤销：谁创建或撤销了消息令牌。
• 意图已创建：为特定邮箱创建了删除意图。
• 意图已确认： 删除请求已被接受。
• 删除已执行： 邮箱已移至最近删除，并开始计算恢复期限。
• 意图已到期：未确认的意图在 10 分钟后到期。
• 邮箱已创建：通过 API 配置了新邮箱。
• 邀请已创建：已发送邮箱设置邀请。
• 转发已更新：邮箱的转发规则已更改。
• DNS 重新检查已触发：已请求验证域名的 DNS。
• 迁移已开始：通过 API 启动了电子邮件迁移。
• 迁移已取消：正在运行的迁移已取消。
• 迁移已重试：失败或已取消的迁移已重试。
• 迁移已删除：迁移记录已删除。
• 消息已读取：通过消息 API 列出或读取了消息。
• 消息已发送：通过消息 API 发送了电子邮件。
• 消息发送失败：电子邮件发送尝试失败。
• 消息标记已更新：消息标记（已读/未读、已加星标）已更改。
• 消息已删除：消息已从邮箱文件夹中删除。
• 消息已移动：消息已在文件夹之间移动。
• 域名已创建：通过 API 添加了域名。
• 域名已删除：通过 API 移除了域名。
• 工单已创建：通过 API 创建了支持工单。
• 工单已回复：已在工单中发布回复。
• 工单已关闭：工单已关闭。
• SMTP 已配置：SMTP 设置已更新。
• SMTP 连接已删除：自定义 SMTP 连接已移除。
• SMTP 测试已排队：SMTP 连接测试已启动。
• Cloudflare 令牌已删除：通过 API 移除了已存储的 Cloudflare 令牌。

所有消息 API 事件，包括读取、发送、标记更新、删除和移动，都会被完整记录。审计记录保留 90 天。

每个事件都会记录使用的令牌、受影响的资源、IP 地址和请求 ID。

可以按事件类型、令牌或日期范围筛选审计日志，以调查特定活动。

快速修复

• 意图在确认前到期： 创建新的删除意图。意图会在 10 分钟后到期。
• "Missing confirm header"： 在确认请求中添加 X-Confirm-Delete: true 标头。
• 确认删除时出现 429： 你已达到每日限制或仍处于冷却期。请等待 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"： 取消现有迁移或等待其完成，然后再开始新迁移。