White Label 品牌 API 与 MCP 指南

您可以通过 API 和 MCP 为每个域名完整配置 White Label 品牌，无需使用控制面板。代理可以设置域名的品牌名称和颜色、上传徽标、启用品牌化控制面板与网页邮箱主机、读取需要创建的 DNS 记录，并请求 DNS 验证。这与控制面板中 Branding 选项卡写入的品牌配置相同；API 只是让代理或脚本代您完成这些操作。

品牌按域名配置（域名使用数字 id）。域名可以使用自己的品牌（custom）、继承账户默认设置（inherit），也可以关闭品牌功能。API 会返回该域名的品牌化主机名和 CNAME 记录。请始终准确复制返回的记录。不要根据本指南中的示例构造主机名或 CNAME 目标。

附加服务权限控制

每种邮件方案都包含 30 天的 White Label 试用和预览。请在向客户开放品牌化主机之前，利用这段时间配置品牌并测试体验。

API 采用与 White Label 控制面板相同的权限：

• **有效试用或付费附加服务：**读取和写入作用域均可用。启用的主机会在 CNAME 解析且 SSL 证书签发后，从 pending_dns 变为 active。
• **取消宽限期：**账户所有者在显示的 hard_delete_at 时间之前保留只读访问权限。写入操作被阻止，委托连接会立即失去 White Label 访问权限。
• **没有有效权限：**White Label 作用域会从凭据的有效权限中移除，其 MCP 工具也不会加载。

如果存储的令牌曾拥有 White Label 作用域，但相关权限已不再有效，API 将返回 403 scope_blocked_by_entitlement 并给出明确的后续操作。创建权限更广的令牌无法绕过此限制。

必需的作用域

品牌功能拥有独立的作用域。这样一来，管理普通域名的自动化就不会意外查看或更改经销商身份。

REST 端点

所有端点都位于 https://trekmail.net/api/v1 下。{id} 是数字域名 id。

除 verify-dns 和 preview 外，每个端点都返回与 GET 相同的品牌载荷，因此一次往返请求即可获知新状态。

品牌载荷

{
  "data": {
    "mode": "custom",
    "white_label_addon_active": true,
    "brand": {
      "id": 42,
      "name": "Northwind Mail",
      "primary_color": "#2563eb",
      "accent_color": "#10b981",
      "logo_url": "https://trekmail.net/storage/branding/42/light.png",
      "logo_dark_url": "https://trekmail.net/storage/branding/42/dark.png",
      "favicon_url": "https://trekmail.net/storage/branding/42/favicon.png",
      "support_email": "support@northwind.com",
      "support_url": "https://help.northwind.com",
      "sender_email": "noreply@northwind.com"
    },
    "mail_zone": {
      "enabled": true,
      "domain": "northwind.com",
      "dns_status": "pending_dns",
      "client_hosts_status": "pending_dns",
      "records": [
        { "type": "TXT", "name": "spf.northwind.com", "value": "v=spf1 include:spf.trekmail.net -all" },
        { "type": "CNAME", "name": "imap.northwind.com", "value": "imap.trekmail.net" },
        { "type": "CNAME", "name": "dav.northwind.com", "value": "trekmail.net" }
      ],
      "dav_url": "https://trekmail.net/dav/files/account/",
      "dav_ready": false,
      "cert_expires_at": null,
      "checked_at": "2026-08-29T06:20:11+00:00"
    },
    "hosts": [
      { "kind": "dashboard", "hostname": "dashboard.northwind.com", "subdomain_label": "dashboard", "enabled": true, "status": "pending_dns" },
      { "kind": "webmail", "hostname": "mail.northwind.com", "subdomain_label": "mail", "enabled": true, "status": "pending_dns" }
    ],
    "dns_records": [
      { "type": "CNAME", "name": "<returned dashboard host>", "value": "<returned CNAME target>", "proxied": false },
      { "type": "CNAME", "name": "<returned webmail host>", "value": "<returned CNAME target>", "proxied": false }
    ],
    "cname_target": "<returned CNAME target>"
  }
}

当 mode 为 off 时，brand 和 mail_zone 为 null。mail_zone.enabled 表示已保存的意图；请使用它的两个状态字段区分等待、活动、失败和清理状态。主机的 status 表示 DNS 和 SSL 是否仍在等待，或主机是否已激活。示例中的占位值是有意设置的：只能发布返回的 dns_records 和 cname_target。

mail_zone 描述品牌自己的邮件主机名（见下文）。dns_status 表示邮件 DNS 状态，client_hosts_status 表示客户端主机和证书状态；两者均可为 off、pending_dns、active 或 failed。records 列出您的提供商需要发布的 DNS 记录。dav_url 始终可以安全使用：在品牌化 DAV 证书和受限网页路由准备就绪之前，它会继续指向 TrekMail。只有当 dav_ready 变为 true 时才切换；此后，cert_expires_at 会报告品牌化邮件应用主机最早的证书到期时间。

读取当前品牌配置

curl -s "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token"

设置品牌（部分合并）

PATCH 是部分合并。您省略的任何字段都会保留，因此只发送要更改的内容。

curl -s -X PATCH "https://trekmail.net/api/v1/domains/123/branding" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-initial" \
  -d '{
    "mode": "custom",
    "name": "Northwind Mail",
    "primary_color": "#2563eb",
    "accent_color": "#10b981",
    "dashboard_enabled": true,
    "dashboard_label": "dashboard",
    "webmail_enabled": true,
    "webmail_label": "mail",
    "mail_zone_enabled": true,
    "support_email": "support@northwind.com",
    "support_url": "https://help.northwind.com",
    "sender_email": "noreply@northwind.com"
  }'

请求正文中的字段：

上传徽标

徽标以 base64 形式传入。slot 为 light、dark 或 favicon。任何槽位都接受 PNG 和 JPG，favicon 还接受 ICO。最大 1 MB。出于安全原因，SVG 会被拒绝。默认的 scope=domain 只会更改 custom 模式下的域名；它不会跟随继承的配置。若要通过 inherit 域名有意更改共享配置，请传递 scope=account_default 并使用不受限制的 branding:write 令牌。受域名限制的令牌无法修改账户默认值。

curl -s -X PUT "https://trekmail.net/api/v1/domains/123/branding/logo/light" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: brand-123-logo-light" \
  -d "{\"content_base64\":\"$(base64 -w0 logo-light.png)\"}"

使用 DELETE 删除槽位：

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding/logo/dark" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-logo-dark-remove"

两者都会返回更新了 logo_url / logo_dark_url / favicon_url 的品牌载荷。PUT 在 JSON 正文中接受 scope；DELETE 将其作为查询参数。对继承配置执行隐式的域名作用域修改会返回 422 inherited_brand。

验证 DNS

创建 CNAME 记录后（参见下面的流程），将验证加入队列：

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/verify-dns" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-verify"

{ "data": { "status": "queued", "hosts": 2 } }

此操作在后台运行。重新读取 GET /branding，观察主机 status 变为 active。如果 White Label 权限失效，请求将返回 403 scope_blocked_by_entitlement，并提供重新激活提示。

如果品牌有邮件区域，该操作还会重新检查邮件区域，因此 mail_zone.dns_status 和 mail_zone.client_hosts_status 会在同一次调用中更新。对于邮件区域，您无需主动调用此操作：我们会定期重新检查等待中的区域，并在记录解析后几分钟内将其启用。verify-dns 只是要求立即检查，而不是等到下一次定期扫描。

在品牌自有域名上使用邮件

mail_zone_enabled 会在客户的邮件应用和 DAV 同步客户端中显示经销商名称。启用它，然后发布 mail_zone.records 中返回的每条记录。其中包括一条 SPF TXT 记录以及 IMAP 和 DAV CNAME 记录。响应中的确切名称和目标是权威值。

当返回的记录要求使用 CNAME 时，请勿使用 A 记录，并让 Cloudflare 云朵保持灰色。邮件和 DAV 客户端必须直接连接；DNS 代理可能破坏证书检查和非浏览器协议。响应会列出您需要发布的每条记录，因此不要添加猜测的邮件记录。

记录解析后，TrekMail 会签发证书并激活主机名。观察 mail_zone.client_hosts_status 变为 active，并观察 mail_zone.dav_ready 变为 true。继续使用返回的 dav_url；只有在可以安全提供 DAV 服务后，它才会从平台地址变为品牌地址。如果主机状态为 failed，请再次运行 DNS 验证；若仍然失败，请提交支持工单。

创建实时预览

POST /branding/preview 会创建一个有效期为 72 小时的 URL，让您能在 DNS 生效前查看品牌体验：

curl -s -X POST "https://trekmail.net/api/v1/domains/123/branding/preview" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-preview"

响应包含一个 72 小时后到期的预览 URL。如果品牌功能已关闭或尚未设置品牌，因没有可预览的品牌，它会返回 422 no_brand。

删除品牌配置

curl -s -X DELETE "https://trekmail.net/api/v1/domains/123/branding?scope=domain" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: brand-123-remove"

scope=domain 只清除此域名；scope=all 清除整个账户的品牌配置。返回品牌载荷。

MCP 工具

white_label 工具集中共有 20 个工具，其中七个用于品牌功能。只有当连接拥有有效的品牌作用域且 White Label 可用时，这些工具才会注册。读取工具需要 branding:read；其他六个工具需要 branding:write。本地托管的 MCP 服务器还可能要求管理员允许写入操作。

get_domain_branding 是只读工具。在所有者取消后的宽限期内，它仍然可用，而全部六个写入工具都会消失。没有 White Label 权限时，tools/list 中不会公布这些工具。

自主端到端流程

如果您的域名 DNS 托管在 Cloudflare，代理可以在无需人工操作的情况下，将没有品牌配置的域名变成可用的品牌化主机，因为现有 Cloudflare DNS 工具（apply_cloudflare_dns）能够写入 get_domain_branding 返回的 CNAME。

1. 设置品牌。 set_domain_branding(mode=custom, name, primary_color, accent_color, dashboard_enabled=true, webmail_enabled=true)。
2. 上传徽标（可选）。调用 set_domain_brand_logo(slot="light", content_base64=…)，然后对 dark 和 favicon 重复操作。
3. 读取 DNS 记录。 get_domain_branding → 复制返回的 dns_records 数组。不要猜测或生成值。
4. 写入 CNAME。 发布这些记录并关闭代理。在 Cloudflare 中，这意味着使用灰色云朵，以便 DNS 和 SSL 验证正常工作。
5. 验证。 verify_domain_branding_dns。
6. 轮询。 重复调用 get_domain_branding，直到每个主机的 status 都变为 active。
7. 预览（可选）。使用 create_branding_preview 获取实时演示 URL，然后再将客户引导到品牌化域名。

实际示例（MCP）

set_domain_branding(
  domain_id=123,
  mode="custom",
  name="Northwind Mail",
  primary_color="#2563eb",
  accent_color="#10b981",
  dashboard_enabled=true,
  webmail_enabled=true,
  support_email="support@northwind.com",
  sender_email="noreply@northwind.com"
)

set_domain_brand_logo(domain_id=123, slot="light", content_base64="iVBORw0KGgo…")
set_domain_brand_logo(domain_id=123, slot="dark", content_base64="iVBORw0KGgo…")

get_domain_branding(domain_id=123)
# → Copy the returned dns_records exactly. Do not substitute an example host or target.

apply_cloudflare_dns(domain_ids=[123])   # writes the CNAMEs, proxy off

verify_domain_branding_dns(domain_id=123)

# poll until active
get_domain_branding(domain_id=123)
# → hosts[].status: "active"

create_branding_preview(domain_id=123)   # optional live demo

请代理报告品牌化主机名及其最终状态，以确认它们确实已经上线，而不只是处于 pending_dns。

注意事项

• **权限控制 API 和 MCP 界面。**写入需要有效试用或付费附加服务。取消后，所有者会获得一个只读恢复窗口；其他所有人会立即失去这些工具。
• **PATCH 是部分合并。**省略的字段会保留。若只更改强调色，请发送 {"accent_color":"#10b981"}。无需重新发送名称、徽标或开关。
• **从关闭状态重新启用需要 mode。**如果品牌功能当前为 off，省略 mode 的 PATCH 不会重新启用它。请传递 mode=custom（或 inherit）以重新启用。
• **sender_email 需要已验证 DKIM 的域名。**设置的发件人地址必须属于账户中已经配置 DKIM 密钥的域名，否则更新会被拒绝。设置自定义发件人之前，请验证域名的 DKIM（retry_domain_dkim / get_dns_check）。
• **徽标使用 base64，≤1 MB，不支持 SVG。**请将 PNG 或 JPG（favicon 也允许 ICO）作为 content_base64 发送。SVG 会被拒绝。请先压缩较大的源文件。
• **不要代理返回的 CNAME 记录。**Cloudflare 橙色云朵或其他 CDN 代理会阻止 DNS 和 SSL 验证。按返回内容发布 dns_records，并设置 proxied:false。
• **写入操作需要正确的访问权限。**除 get_domain_branding 外，每个工具都会更改数据，因此请使用必需的写入作用域；如果本地 MCP 管理员选择保护写入，还需启用写入操作。