API 权限范围与套餐权限指南

权限范围精确控制 API 令牌可以执行的操作。每个令牌都带有一组权限范围，API 会在每次请求时检查这些范围。

权限范围的工作方式

创建令牌时，你需要选择要包含的权限范围。API 对每个请求应用三项上限：

1. 账户权益： 当前套餐和有效的附加组件决定现在可用的功能。
2. 成员资格： 获得委派权限的人员不能授予或使用超出其当前角色和域名访问权限的能力。
3. 凭据授权： 令牌或 OAuth 同意必须包含端点要求的权限范围。

错误会指出未通过的上限。insufficient_scope 表示凭据从未获得该权限范围，scope_blocked_by_membership 表示人员角色的权限更窄，scope_blocked_by_entitlement 表示所需的 White Label 权益未激活。

两层权限范围：OAuth 和 API 权限范围

OAuth 支持六个旧版便利权限包、所有细粒度 API 权限范围，以及仅控制公开范围的 tools:* 选择器。旧版权限包如下：

每个旧版 OAuth 权限包都会展开为细粒度 API 权限范围，例如 domains:read 和 drive:account:write。新集成可以直接请求这些细粒度范围。White Label 权限范围有意不包含在旧版 mail:* 权限包中，因此现有连接器不会在升级后自动获得经销商管理权限。它必须明确请求所需的 White Label 范围。tools:white_label 选择器会限制 MCP 中公开的工具，但本身不授予任何 API 权限。

三种连接方式及各自授予功能的方法

代理或集成可以通过三种方式访问 TrekMail，并且每种方式的门控机制不同。这一点很重要，因为 MCP 的“功能标志”（TREKMAIL_ALLOW_DESTRUCTIVE、TREKMAIL_ALLOW_SENDING、TREKMAIL_ALLOW_MIGRATION）只存在于其中一种方式中。

简而言之：托管式 HTTP MCP 根据 OAuth 凭据筛选其公布的工具；stdio MCP 取令牌范围、工具集、只读模式和本地安全控制的交集；REST API 则直接由令牌携带的细粒度范围控制。在所有模式中，运行时 API 授权仍具有最终决定权。

权限范围参考

账户与账单

billing:autopay 是唯一会转移资金的权限范围，因此值得仔细阅读两遍。

它有意与 billing:read 分开：允许查看账单的连接不能 增加账单金额，授予账单只读权限也不等于同意支出。它绝不会 自动包含在内，令牌或连接只有在你明确授予时才会获得它，而且它不属于 任何旧版粗粒度权限包，因此在此范围出现前授权的连接 无法花费任何资金。

它允许购买电子邮件验证额度和开通订阅。它完全不 允许取消、降级或更改现有订阅。这些操作没有 端点。无论有多少连接持有该范围，整个账户的支出还会受到 单次、每日和每月限制。

它适用于所有套餐，因为所有套餐都销售验证额度，包括 Nano。

域名

Starter 即支持域名别名投递。Starter 令牌可以读取已保存状态和实时状态；通过 API/MCP 连接、更改或移除别名需要 Pro/Agency 的 domains:write 功能。Starter 用户仍可通过控制面板更改。请参阅通过 API 和 MCP 使用域名别名。

White Label

这些操作令牌范围仅在 White Label 试用或付费附加组件有效时出现。在取消后的宽限期内，所有者保留读取范围；委派成员和所有写入范围都会被移除。

实时成员资格还会施加另一项上限。客户或团队成员无法通过创建范围更广的令牌来扩大自己的角色、域名访问权限或自定义权限。请参阅使用 API 和 MCP 管理 White Label 团队。

邮箱

消息（消息令牌）

消息权限范围由消息令牌（前缀 tm_msg_）携带，而不是操作令牌（前缀 tm_live_）。消息令牌通过 API 使用具有 mailboxes:message-tokens:manage 范围的操作令牌创建。除普通发送路径的限制外，它们还有 API 专用保护：默认情况下，每个令牌每分钟允许 30 个读取请求，每天允许 5,000 次成功读取；每个令牌每分钟允许 60 个发送请求，整个邮箱每天允许通过 API 发送 100 封邮件。第二个令牌安全计数器默认为每天 500 次发送，因此通常是较低的邮箱上限生效。

所有新的 Webmail API 端点（联系人、日历、身份、模板、已阻止发件人、草稿、定时发送、文件夹、附件）都映射到现有的三个消息权限范围，并未添加新范围。现有令牌无需任何更改即可继续工作。

messages:read 不授予写入访问权限。在托管式 OAuth 中，批准范围更广的 messages:send 功能会同时配置读取、写入和发送访问权限；手动创建的 tm_msg_ 令牌则严格保留创建时选择的范围。

支持工单

Starter： 通过 API 只能读取。请通过控制面板创建和回复工单。

SMTP 配置

SMTP 按域名配置（/api/v1/domains/{id}/smtp），单一账户级默认值（/api/v1/smtp/default）决定新域名的初始配置。完整端点列表请参阅 API 概览。旧版账户级 /api/v1/smtp 端点仍会响应以保持兼容性，但不再控制路由。

迁移

迁移权限范围由操作令牌（前缀 tm_live_）携带。Starter 可以通过 API 查看迁移，并从控制面板运行迁移。Pro 和 Agency 还可以通过 API 和 MCP 开始、取消、重试和删除迁移。

Cloudflare

Drive

Drive 权限范围属于操作令牌范围。令牌可以限制到选定邮箱，Drive 会对该令牌隐藏其他邮箱空间。购买、调整大小和取消 Drive 附加组件并非 API/MCP 写入操作；账单更改仍需在控制面板中完成。

Nano + Drive 附加组件： 激活 Drive 存储附加组件后，Nano 将获得完整的 Drive 权限范围集。不会解锁其他内容，只有 Drive 以及 Nano 已拥有的电子邮件验证器范围。如果取消附加组件，读取范围会在 7 天宽限期内继续有效，以便你完成下载或迁出；写入、共享和永久清除权限会立即停止。

电子邮件验证器

电子邮件验证器权限范围适用于所有套餐，包括 Nano。唯一限制是你的额度余额。完整端点参考请参阅电子邮件验证器 API。

套餐访问级别

White Label 权限范围是附加功能，并非 Pro 或 Agency 基础套餐的一部分。只有当这些账户的 White Label 权益有效时，它们才会出现。

降级后会发生什么

如果从 Pro 降级到 Starter，具有写入范围的现有令牌不会被删除。API 会在运行时阻止使用不允许范围的请求。

例如，Starter 套餐中具有 mailboxes:create 的令牌在尝试创建邮箱时会收到 403，错误代码为 token_scope_blocked_by_plan。同一令牌的读取范围仍可继续使用。

要解决此问题，请撤销旧令牌，并创建仅含当前套餐所允许范围的新令牌。

危险权限范围

mailboxes:delete、domains:delete、migrations:write 和 cloudflare:delete 权限范围在控制面板中标记为危险。具有这些范围的令牌可以发起邮箱或域名删除、移除 Cloudflare 令牌，或执行其他不可逆操作。请考虑你的使用场景是否确实需要它们。

对于本地托管的 MCP 服务器，管理员可以要求设置 TREKMAIL_ALLOW_DESTRUCTIVE=true，之后删除工具才可用。托管式 MCP 使用 OAuth 期间批准的权限范围。

messages:send 权限范围允许从邮箱发送真实电子邮件。在本地托管的 MCP 服务器中，每次发送还可以要求设置 TREKMAIL_ALLOW_SENDING=true 并传入 confirm_send=true。详情请参阅安全防护与删除意图。

migrations:write 权限范围允许启动使用已保存凭据连接外部 IMAP 服务器的电子邮件迁移。在本地托管的 MCP 服务器中，迁移写入还可以要求 TREKMAIL_ALLOW_MIGRATION=true 和每次调用的确认参数（confirm_start、confirm_cancel、confirm_retry）。

域名限制

权限范围控制令牌可以执行什么操作。域名限制控制它可以在什么位置执行这些操作。

限制到特定域名的令牌只能查看和修改这些域名内的资源。这样可以让承包商或代理访问单个客户域名，而不会公开其他域名。

权限范围检查先于域名限制检查。如果令牌缺少所需范围，无论域名限制如何，请求都会以 403 失败。

快速修复

• 403 "insufficient_scope"： 令牌没有此端点所需的范围。请使用正确范围创建新令牌。
• 403 "token_scope_blocked_by_plan"： 套餐不再允许令牌的一个或多个范围。请升级套餐，或者撤销令牌并使用允许的范围创建新令牌。
• 403 "scope_blocked_by_entitlement"： White Label 未激活，或在取消宽限期内尝试了写入操作。请先重新激活，再重新授权连接。
• 403 "scope_blocked_by_membership"： 当前成员角色或自定义权限不允许此操作。请让账户所有者更改该成员资格。
• 创建表单中隐藏了某些范围： 你的套餐不支持这些范围。表单只显示允许的范围。