通过 API 和 MCP 管理已连接账户

已连接账户让网络邮箱能够读取外部邮箱中的邮件并通过其发送邮件，包括 Gmail、Yahoo、iCloud、Outlook.com/Microsoft 365 或任何 IMAP 服务器。消息 API 和 MCP 工具以编程方式提供相同的功能：你可以列出、添加、测试、编辑和删除已连接账户，也可以将常规消息调用（列出、读取、发送、标记、移动、删除和文件夹）指向已连接账户，而不是令牌自己的邮箱。

简单来说：mailbox_id 选择代理可以代表其操作的 TrekMail 邮箱，而 external_account_id 选择其中的 Gmail 或其他已连接邮箱。两者不能互换。

套餐、限制和目录大小

已连接账户管理提供七种消息工具。限定权限范围的令牌只会看到它实际可以使用的工具，而不是完整的产品目录。

开始之前

• 已连接账户是网络邮箱功能，使用消息令牌接口 (/api/v1/messages/...)。它由具有下列权限范围的消息令牌授权，而不是控制面板 API 令牌。
• 套餐限制适用于每个邮箱：Starter 5, Pro 10, Agency 30。Nano 套餐不包含已连接账户。
• 每个 endpoint 都限定于令牌自己的邮箱。令牌只能查看和管理自己的已连接账户，不能访问其他邮箱的账户。
• 凭据和 OAuth 令牌在响应中始终会被遮蔽。你可以写入密码或应用专用密码，但永远无法将其读回。
• Outlook.com 和 Microsoft 365 账户通过网络邮箱界面中的 Microsoft 登录 (OAuth) 进行连接。连接后，API 可以管理和使用这些账户，但不会执行交互式 Microsoft 同意步骤。

权限范围

在消息调用中指定已连接账户，需要该调用原本要求的相同权限范围（例如，列出其邮件需要 messages:read；发送邮件需要 messages:send）。

管理已连接账户

基础路径：/api/v1/messages/external-accounts

添加账户

POST /api/v1/messages/external-accounts
Scope: messages:write

请求正文：

请先调用 POST /external-accounts/detect，自动填写 provider 和服务器设置。存储调用会在保存前进行真实的 IMAP + SMTP 测试。返回 422 并带有错误类别 (auth、tls、network、transient_throttle)，表示凭据无效且没有存储任何内容。

在消息调用中指定已连接账户

每个操作邮箱的消息 endpoint 都接受可选的 external_account_id。提供该值可对相应的已连接账户执行调用，而不是令牌自己的邮箱；省略该值则使用邮箱本身。这适用于列出、读取、发送、回复、标记、移动、删除以及文件夹列表。

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

仅使用 external_account_id 发送时，邮件会通过该账户自己的 SMTP 服务器发出（使用其提供商的 SPF/DKIM）。如果改为提供与来源绑定的 identity_id，则会使用该发件人身份的域名或已保存配置文件路由，同时仍将已发送副本保存在已连接的收件箱中。账户必须处于正常状态 (status: active)；已断开连接的账户会返回错误，要求你重新连接。请参阅通过 API 和 MCP 使用发件人地址。

MCP 工具

AI 代理也可以通过 MCP 使用相同功能（包括专用 stdio 服务器和公共 MCP 服务器）：

消息工具 list_messages、read_message、send_message、list_folders、update_message_flags、move_message、delete_message、prepare_reply、prepare_reply_all 和 prepare_forward 接受可选的 external_account_id 参数。发送、创建草稿和定时发送也接受与来源绑定的 identity_id，该值由 list_identities 返回。

由于管理工具会使用用户提供的凭据与任意邮件服务器建立出站连接，因此它们采用与已连接账户其余功能相同的安全措施：主机允许列表、阻止私有地址范围、端口允许列表以及每个主机的连接上限。