创建并管理 TrekMail API 令牌

API 令牌控制应用或智能体能在您的账户中执行哪些操作。每个令牌都有名称、权限范围、可选的域限制和到期日期。

要连接 MCP 客户端？ 如果客户端支持浏览器授权，请将 https://trekmail.net/mcp 添加为远程 MCP 服务器，并在浏览器中批准访问。通常无需创建或粘贴令牌。手动 tm_live_ 令牌适用于脚本、CI 任务、自托管 MCP，以及不支持此流程的客户端。请参阅连接 AI 智能体 (MCP)。

开始之前

• 所有套餐都可以创建 API 令牌，包括 Nano。Nano 套餐仅限使用 Email Verifier 权限范围 (verify:read、verify:write)。
• Starter 套餐允许使用只读基础设施权限范围，以及完整的 Drive 和 Email Verifier 权限范围。Starter 还可以在控制面板中管理转发，但通过 API 写入转发设置 (mailboxes:forwarding:write) 需要 Pro 或 Agency。Pro 和 Agency 会开放所有权限范围。
• 所有者可以管理账户的所有凭据。拥有 API 令牌权限的受委派成员只能管理自己创建的凭据，并且只能授予其成员权限中已有的权限范围和域。
• 提示： 在“AI 智能体和 API”页面点击开始导览，快速了解连接选项、令牌、已连接应用和审计日志。

创建 Drive 自动化令牌

Drive API 和 MCP 工具使用操作令牌 (tm_live_...)。请仅选择工作流需要的 Drive 权限范围：

• 只读报告：drive:account:read、drive:mailbox:read 或 drive:addon:read。
• 上传自动化：添加 drive:account:write 或 drive:mailbox:write。
• 公开交付链接：添加 drive:account:share 或 drive:mailbox:share。
• 永久清理：仅在单独且受到严格控制的令牌中使用 drive:account:purge 或 drive:mailbox:purge。

无法通过 API 令牌购买 Drive 附加服务、调整其大小或取消它。智能体可以使用 drive:addon:read 读取附加服务状态和价格，但订阅变更仍需在控制面板中完成。

创建 White Label 自动化令牌

White Label 使用五个操作令牌权限范围：branding:read、branding:write、members:read、members:write 和 activity:read。仅当账户拥有 White Label 访问权时，它们才会显示。members:write 被标记为危险，因为它可以移除访问权并撤销其他人的密钥。

对于只读状态和审计集成，请选择 branding:read、members:read 和 activity:read。仅在设置品牌和 DNS 时添加 branding:write。只有当自动化必须邀请或修改人员时，才添加 members:write。

在取消宽限期内，所有者保留三个读取权限范围以便恢复，但写入操作和受委派的 White Label 凭据会停止工作。重新激活不会恢复已撤销的凭据；请创建或授权新凭据。

创建令牌

1. 前往 AI 智能体和 API → 令牌。
2. 点击创建令牌。
3. 填写表单：
   • 名称： 用于识别令牌的标签，例如“Claude 智能体”或“CI/CD 管道”。
   • 到期时间： 选择 7 天、30 天、90 天、自定义日期或永不到期。
   • 权限范围： 选择令牌可以执行的操作。默认勾选所有允许的权限范围。
   • 域限制： 选择“所有域”，或选择特定域来限制令牌的访问权。
4. 点击创建令牌。

创建后，明文令牌只显示一次。请立即复制，或使用下载按钮将其保存为 .txt 文件。

令牌无法再次查看。 关闭确认窗口前，请将其安全保存。

创建消息令牌

消息令牌让智能体能够从指定邮箱读取和发送邮件。它们与操作令牌分开，并使用操作令牌通过 API 以编程方式创建。

要创建消息令牌，智能体应调用：

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

请选择工作流所需的最小权限范围：

明文令牌 (tm_msg_...) 只返回一次。请将其作为 TREKMAIL_MESSAGE_TOKEN 添加到 MCP 配置中。

消息令牌适用于 Pro 和 Agency 套餐。操作令牌必须拥有 mailboxes:message-tokens:manage 权限范围。

对于已连接的 Gmail 或其他外部收件箱，请使用 external_account_id。如果希望收件人看到已授权的企业地址，还要使用身份 endpoint 返回的 identity_id。请参阅通过 API 和 MCP 使用“发件人”地址。

令牌格式

TrekMail 使用两种令牌前缀来区分令牌类型：

前缀后的前 8 个字符会作为可见前缀存储在控制面板中，便于识别。

权限范围

权限范围控制令牌可以执行的操作。可选内容取决于您的套餐：

• Nano： 仅限 Email Verifier (verify:read、verify:write)。添加 Drive Storage 后，账户还会获得其有权使用的 Drive API 和 MCP 功能。
• Starter： 完整的 Drive 和 Email Verifier 访问权，以及对其他所有内容的只读访问权（域、邮箱、转发、邮件过滤器、自动回复、迁移、工单、SMTP、Cloudflare）。对于 Starter 未通过 API 开放的写入操作，请使用控制面板，例如创建迁移、回复工单或更改自动回复。
• Pro 和 Agency： 完整访问权。可以在所有功能系列中读取、写入、创建和删除，还可使用消息令牌通过 API 读取和发送邮件。

White Label 权限范围属于附加服务权益，并不是绕过套餐表的捷径。它们仅在 White Label 激活时提供；在取消宽限期内，所有者保留只读恢复访问权。

有关各权限范围的说明，请参阅 API 权限范围和套餐许可。

域限制

默认情况下，令牌可以访问账户中的所有域。要将令牌限制到特定域：

1. 在域限制部分选择选定的域。
2. 勾选令牌应访问的域。

受限令牌尝试访问其他域上的资源时会收到 404 响应；API 的行为就像这些域不存在一样。

撤销令牌

1. 前往 AI 智能体和 API → 令牌。
2. 在列表中找到令牌。
3. 点击撤销。
4. 确认撤销。

已撤销的令牌会立即停止工作。任何使用已撤销令牌的 API 请求都会收到 401 Unauthorized。

撤销是永久性的，无法撤回。如需恢复访问，请创建新令牌。

令牌状态

令牌有三种状态：

使用“令牌”页面上的状态过滤器按状态查看令牌。

审计记录

每次创建和撤销令牌都会显示在审计日志选项卡中。事件包括令牌名称、操作和时间。

快速解决方法

• “您的套餐不提供这些权限范围”： 您的套餐不包含这些权限范围。Nano 仅限 verify:read 和 verify:write（添加 Drive Storage 附加服务后还可获得 drive:* 权限范围）。Starter 增加对所有基础设施功能系列的读取访问权，以及完整的 Drive 和 Email Verifier 访问权。Pro 和 Agency 开放所有写入操作。
• 丢失明文令牌： 无法恢复令牌。请撤销它并创建新令牌。
• 令牌有效，但对某些域返回 404： 令牌可能设置了域限制。请撤销令牌并使用“所有域”重新创建，或将缺少的域添加到限制中。
• White Label 权限范围返回 scope_blocked_by_entitlement： 重新激活 White Label，然后创建或授权拥有所需权限范围的凭据。
• 受委派令牌在角色变更后停止工作： 减少、暂停或移除成员访问权会立即撤销受影响的凭据。所有者恢复正确访问权后，请创建新令牌。