通过 API 和 MCP 使用发件人地址

TrekMail 将使用不同凭据和权限的两项工作分开处理：

1. 控制面板/Ops 接口管理可重复使用的 SMTP 配置文件和域名路由。它使用 tm_live_ 令牌，该令牌具有 smtp:read 或 smtp:write 权限。
2. 网络邮箱/消息接口管理一个邮箱和一个已连接收件箱可用的发件人地址。它使用 tm_msg_ 令牌，该令牌具有 messages:read、messages:write 或 messages:send 权限。

这种划分是有意为之。邮箱令牌可以选择已经授权的发送路由，但不能泄露 SMTP 凭据，也不能管理其他账户的基础设施。

简要说明

• 如果仅使用 external_account_id 发送，收件人会看到该已连接账户自己的地址，并使用它自己的 SMTP 服务器。
• 如果还发送与来源绑定的 identity_id，收件人会看到该身份的企业地址。TrekMail 使用分配给该身份的域名路由或已保存的 SMTP 配置文件，然后将已发送副本保存在已连接的收件箱中。
• Starter 可以在网络邮箱中配置和使用此功能。Pro 和 Agency 还可以通过 API 或 MCP 将其自动化。Nano 没有已连接账户名额。

可用的 API 和 MCP 工具会随产品发展而变化。以其他地址发送功能使用 SMTP 和消息工具系列，每个连接只会看到其套餐、权限范围和已批准权限允许的工具子集。

路由模型

发送 external_account_id 而不发送 identity_id 时，TrekMail 会通过该外部账户自己的 SMTP 服务器发送，并使用其自己的地址。

同时发送两个值时，TrekMail 将外部账户视为收件箱/已发送目标位置，将身份视为可见发件人 + SMTP 路由：

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

身份和外部账户必须相互绑定。省略来源或提供其他邮箱的身份会返回 422 identity_unavailable。

1. 在控制面板 API 中检查或配置 SMTP

使用 Ops 令牌。

读取配置文件绝不会返回密码。代理可以通过使用情况 endpoint 安全地说明编辑或删除共享配置文件前的影响。

MCP 工具：get_domain_smtp、set_domain_smtp、list_domain_smtp_profiles、get_domain_smtp_profile_usage、create_domain_smtp_profile、update_domain_smtp_profile、delete_domain_smtp_profile、test_domain_smtp、get_domain_smtp_test_status、get_account_smtp_default、set_account_smtp_default。

2. 列出指定收件箱的地址

使用消息令牌：

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

响应包含特定于来源的 identities、所有已配置的 external_identities、sending_addresses、符合条件的 send_as_domains、邮箱的 reply_from_policy，以及仅为账户所有者邮箱提供、可直接选择的已保存 smtp_profiles。

MCP：调用 list_identities 并提供 external_account_id。

托管 MCP 与本地 stdio

消息工具在传输方式上有一个重要区别：

• **托管 HTTP MCP (OAuth)：**每次调用消息工具时还要传递 mailbox_id。托管服务器使用该值为指定邮箱创建短期消息令牌。例如，调用 list_identities 并提供 { "mailbox_id": 7, "external_account_id": 42 }。
• **自行托管的 stdio MCP (tm_msg_)：**不要传递 mailbox_id。静态消息令牌已经绑定到一个邮箱，因此工具架构只需要 external_account_id。

external_account_id 绝不会替代 mailbox_id：它在已经授权的邮箱内选择一个已连接收件箱。控制面板 SMTP 工具仍限定于账户，在两种传输方式中都不接受 mailbox_id。

3. 创建发件人身份

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email 必须已经是该邮箱的主地址或已启用发送的有效别名。其域名必须处于有效状态，并且属于同一账户。smtp_mode: domain 遵循控制面板中配置的域名路由。smtp_mode: profile 将身份固定到 smtp_connection_id；只有账户所有者邮箱才能直接选择配置文件。

external_account_id 是可选的，准确理解它的含义很重要：

• 如果通过已连接的 Gmail、Outlook 或 IMAP 收件箱读取该地址的邮件，请包含该值。身份随后会绑定到该收件箱，并且只能与它一起使用。
• 如果邮件改为转发到 TrekMail 邮箱，请省略该值。这是共享收件箱工作流：客户将邮件保留在自己的提供商处，并将副本转发到团队邮箱。身份属于邮箱本身，每个具有发送权限的成员都可以使用它。

个人已连接收件箱绝不能附加到共享邮箱：它仅属于连接它的用户。此时请省略 external_account_id。

MCP：调用 create_identity 并使用 kind=send_as。在托管 MCP 上，请按上述说明包含父级 mailbox_id。

4. 发送、创建草稿、定时发送、回复或转发

常规消息操作接受同一组来源值：

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

立即发送、保存/更新草稿和定时发送都支持 identity_id。回复/转发准备接受 external_account_id，并根据投递标头选择匹配的身份。队列中的消息实际运行时，会重新授权所选身份；禁用其别名、域名、配置文件或已连接账户会停止投递，而不会静默改用其他发件人地址。

MCP 工具：send_message、save_draft、update_draft、schedule_message、prepare_reply、prepare_reply_all 和 prepare_forward。

回复策略

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient 会尽可能从收到邮件的地址回复。对于普通邮箱邮件，default 始终从邮箱默认地址开始。MCP 使用 set_reply_from_policy。

安全和隔离规则

• SMTP 凭据绝不会进入消息 API 或 MCP 响应。
• 每个外部账户和身份都限定于消息令牌的邮箱。
• 已连接的发件人身份只能与其对应的 external_account_id 一起使用；邮箱所有的身份只能在不提供该值时使用。
• 发件人地址必须已经被授权为邮箱地址或已启用发送的别名；API 不能虚构任意发件人地址。
• 创建前必须有可用路由，投递时会再次检查。
• 自定义 Reply-To 标头不能与身份已保存的 Reply-To 冲突。
• 通过 MCP 更改身份和配置文件需要相应的写入权限。本地托管的 MCP 管理员可以要求明确批准写入操作；发送也需要逐封邮件确认。

不需要新的令牌权限范围字符串。现有的 smtp:* 和 messages:* 令牌会继续按照当前权限工作。

应用哪个发送限制？

API 调用也保留自己的滥用防护：默认情况下，每个消息令牌每分钟可发送 60 个请求，整个邮箱每天可通过 API 发送 100 封邮件。无论最终由哪个服务器投递邮件，这些限制都适用。