使用 API 和 MCP 管理白标团队

无需切回控制面板即可管理白标账户。REST API 和 MCP 服务器涵盖账户设置状态、客户和团队成员、角色、域名访问权限、邀请、暂停、移除、恢复以及活动历史记录。品牌设置由同一套白标工具及其专属的品牌指南涵盖。

关键边界很简单：连接绝不能授予超过其背后人员已有权限的访问权。仅限特定域名的管理员无法邀请他人访问无关域名，自定义角色也不能授予调用者本身不具备的权限。

可用功能

完整的 MCP 目录目前包含通过 stdio 提供的 261 个工具，以及最多通过托管 HTTP 提供的 260 个工具。白标功能提供 20 个工具：七个用于品牌管理，13 个用于账户、成员和活动管理。

这些工具并非向所有人加载。TrekMail 会先评估账户当前的白标权益、人员当前的成员资格、令牌或 OAuth 授权、任何域名限制、选定的工具集和本地安全设置，然后再构建 tools/list。没有白标访问权限的连接完全不会收到这些模式。

权益状态

拥有白标读取权限时，可调用 GET /api/v1/white-label 或 get_white_label 工具来区分 active 和只读的 grace，并查看设置进度和宽限期截止时间。不可用的账户无法调用该端点：如果存储的凭据仍指定账户已无法使用的白标范围，API 会返回 scope_blocked_by_entitlement 并说明在哪里重新激活。

范围

成员活动端点同时需要 activity:read 和 members:read，因为它的响应既包含成员记录，也包含活动。托管 OAuth 连接使用 tools:white_label 选择器来请求此工具系列；有效的 REST 范围仍受账户和成员资格限制。

对于自行托管的 MCP 服务器，使用工具集允许列表时，请将 white_label 添加到 TREKMAIL_TOOLSETS。写入工具还遵循下文所述的本地安全门控。

REST 端点

所有路径都位于 https://trekmail.net/api/v1 下。

此表中的每个写入操作都需要 Idempotency-Key 标头。使用相同密钥重复同一请求会返回最初的安全结果；重放中的一次性机密信息会被遮盖，例如邀请令牌。使用相同密钥提交不同正文会返回 idempotency_mismatch。

先读取访问目录

不要在集成中硬编码角色权限。请在发出邀请或更改访问权限前调用访问目录。其 grantable 标志反映调用者当前的成员资格，并可能在所有者调整该成员资格时发生变化。

目前可用于新邀请的角色包括：

• client - 管理分配的域名和邮箱，但看不到经销商与 TrekMail 的私有关系。
• webmail_only - 显示在团队列表中，但不获得控制面板权限。
• domain_admin - 管理分配的域名及其 DNS，但不管理邮箱。
• mailbox_operator - 管理所分配域名内的邮箱，但不管理域名本身。
• read_only - 可以检查允许访问的账户界面，但不能进行更改。
• custom - 仅获得 permissions 中列出的权限。

某些角色需要显式的 domain_ids；其他角色可以使用 all_domains。访问目录会说明适用的规则。如果调用者试图授予更广泛的角色、权限或域名集合，TrekMail 会返回 scope_blocked_by_membership，而不是静默缩小邀请范围。

邀请客户

curl -s -X POST "https://trekmail.net/api/v1/white-label/members" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-northwind-admin-20260904" \
  -d '{
    "email": "admin@northwind.example",
    "role": "client",
    "all_domains": false,
    "domain_ids": [123, 124],
    "note": "Northwind primary contact"
  }'

响应包含成员、电子邮件是否发送成功，以及一次性邀请 URL。投递问题不会删除邀请：所有者可以复制 URL，也可以稍后重新发送。

对于自定义角色，请从访问目录读取 grantable_permissions，并在 permissions 中发送选定的值。至少需要一项权限。

跟踪成员状态

每个成员响应都包含 allowed_operations。请使用此列表，不要猜测：

• 待处理的邀请可以更新、暂停、重新发送或移除。
• 有效成员可以更新、暂停或移除。
• 已暂停的成员可以更新、恢复或移除。
• 已移除的成员可以还原。
• 所有者行会显示以提供上下文，但无法通过这些端点更改。

此列表还会针对当前调用者进行筛选。对于只读连接、调用者自己的成员资格，以及权限超出调用者管理范围的成员，该列表为空。

调用者不能移除或暂停自己。受委派的调用者也无法管理访问权限比自己更广泛的成员。无效的转换会返回 membership_state_conflict，并提示重新读取成员。

暂停或移除某人会撤销在该成员资格下创建的 API 和邮箱密钥。恢复或还原成员资格绝不会带回这些旧密钥；该人员必须重新连接或创建新凭据。

活动和隐私边界

GET /white-label/activity 返回邀请、角色和域名更改、暂停、移除、还原以及相关安全操作。可使用 action、member_id 和 per_page 进行筛选。

GET /white-label/members/{id}/activity 将该成员的账户操作与近期登录记录结合起来，包括时间、IP 地址、大致位置、浏览器、操作系统和设备类型。此路由特意要求两个读取范围。受域名限制的调用者只能请求完全位于其域名边界内的成员；无法访问的成员会以 404 返回，因此该端点不会泄露其他租户或客户的存在。

MCP 工具

邀请工具要求在自行托管的 stdio MCP 上设置 TREKMAIL_ALLOW_SENDING=true。更改访问权限的工具要求设置 TREKMAIL_ALLOW_DESTRUCTIVE=true；移除操作还要求 confirm_remove=true。这些开关是本地安全控制，并非额外的 API 权限。托管 MCP 会应用其自身获批的安全策略。

如果没有提供幂等密钥，这些工具会创建确定性密钥。当工作流可能在不同进程中重新启动时，提供自己的 idempotency_key 很有用。

安全的自动化流程

1. 调用 get_white_label。遇到 scope_blocked_by_entitlement 时停止；如果成功响应为 grace，则仅继续读取操作。
2. 在授予访问权限前立即调用 get_white_label_access_catalog。
3. 更改目标成员前先列出或读取该成员。
4. 检查 allowed_operations、预期角色、权限和域名 ID。
5. 对写入操作使用稳定的幂等密钥。
6. 再次读取成员，并报告最终状态和有效权限。
7. 需要更改的审计记录时，检查白标活动。

指明后续操作的错误