通过 API 和 MCP 管理域名别名

域名别名让一个域名沿用另一个域名的收件地址。如果 hello@company.example 能接收邮件，hello@brand.example 就能将邮件投递到同一位置，而无需创建和维护第二个邮箱或别名。

此功能仅用于接收。它不会创建发件地址、改变 SMTP，也不会允许任何人以连接域名的身份发送邮件。

适用场景

当企业拥有多个品牌域名、仍接收客户邮件的旧域名，或需要共用相同收件箱名称的独立国家域名时，域名别名非常实用。

例如：

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

@ 前的部分保持完全相同。如果主域名上没有对应地址，TrekMail 不会自行创建。

套餐和限制

一个连接域名每次只能跟随一个主域名。一个主域名可以服务多个连接域名，但不得超过账户的一般域名限制。一个域名不能同时作为连接域名和主域名，这可简化路由并防止循环。

两个域名必须属于同一账户、使用 TrekMail 接收入站邮件、处于活动状态并有正常的 MX 记录。如果套餐、账户或 DNS 状态之后发生变化，TrekMail 会保留已保存的连接，但暂停投递，直到重新满足要求。

保持优先级的项目

TrekMail 先检查连接域名上已配置的精确地址，然后才运行域名别名。现有邮箱、别名、转发地址、邮箱转发和 catch-all 设置保持文档中规定的优先级。

因此，特意设置的 sales@brand.example 规则不会被 sales@company.example 悄然替换。

REST API

三个 endpoint 都使用连接域名的 ID：

Endpoint 保留原始 /matching-addresses 路径，以免破坏现有集成。控制面板和文档使用更清晰的行业术语 域名别名。

PUT 和 DELETE 需要 Idempotency-Key 标头。使用相同密钥重复同一成功请求是安全的。

连接域名

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

读取结果

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured 表示连接是否已保存。delivering 表示目前是否正常工作。请同时检查两者，不要把保存的记录视为邮件正在流转的证明。

当令牌可访问连接域名但无法访问主域名时，响应会将 primary_domain_restricted 设为 true 并隐藏主域名身份。它绝不会泄露令牌允许列表之外的域名。

投递状态

MCP 工具

同一流程可通过三个域名工具完成：

• get_domain_alias：读取已保存连接和实时投递状态；
• set_domain_alias：连接或更改主域名；
• remove_domain_alias：在 confirm_remove: true 后断开连接。

托管 MCP 应用 OAuth 期间批准的权限。本地托管 MCP 的管理员可要求明确批准写入操作。两种方式都会强制执行账户套餐、令牌范围、域名允许列表和服务器端验证。

工具名称和面向客户的标题使用 域名别名。REST endpoint 为兼容性保留原始路径。

安全移除和降级

移除连接不会删除任何域名或邮箱。精确邮箱、别名、转发地址和 catch-all 规则保持不变。仅依赖匹配功能的未匹配地址可能开始退信，因此确认移除前请检查域名。

删除连接域名会自动移除其连接。只要仍有连接域名依赖主域名，TrekMail 就不会删除该主域名；请先断开这些域名。

降级到 Nano 后，连接仍会保存但停止投递。恢复到 Starter 或更高套餐后，无需重新输入主域名即可恢复连接。

审计记录

每次 API 或 MCP 更改都会显示在 AI 代理和 API → 审计日志 中。连接和更改事件记录两个域名 ID、适用时的旧主域名、操作令牌、请求 ID 和时间。移除事件记录被移除的连接。事件不会记录邮件内容或凭据。

故障排查清单

1. 确认两个域名均显示为 活动，并使用 TrekMail 接收入站邮件。
2. 检查两个域名的 MX 记录是否正常。
3. 确认账户使用 Starter、Pro 或 Agency。
4. 同时查看 configured、delivering、status 和 paused_reason。
5. 检查精确邮箱、别名、转发地址或 catch-all 规则是否已负责该地址。
6. 在审计日志中查看最近的连接、更改或移除操作。