通过 API 和 MCP 配置邮件客户端

TrekMail 通过 REST 和 MCP 提供控制面板中 应用和设备所使用的相同连接数据。两个接口均为只读，并要求邮箱读取权限。

它们绝不会返回邮箱密码或自定义 SMTP 提供商的凭据。用户直接在邮件应用中输入邮箱密码。即使域名通过自定义提供商发送邮件，外部应用也会向 TrekMail 的公开 SMTP endpoint 提交邮件；TrekMail 会在内部应用私有域名路由。

获取连接设置

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

所需内部权限范围：mailboxes:read。令牌的可选 domain_ids 和 mailbox_ids 限制会被强制执行。

响应包含：

• 入站 IMAP 主机、SSL 端口、用户名和就绪状态；
• 出站 SMTP 主机、SSL 端口、用户名和就绪状态；
• 日历和联系人的 DAV 服务器 URL、连接就绪状态以及返回地址是否带品牌；
• 应用和设备中显示的 Gmail、Outlook、Apple Mail、Thunderbird 和通用 IMAP 三步本地化指南；
• sending.mode：platform、profile 或 not_configured；
• sending.reason：出站邮件未就绪时稳定且机器可读的原因；
• apple_mail_profile.available，仅当接收和发送都就绪时为 true；
• shared_mailboxes.native_access_enabled、配置的命名空间，以及委派给此普通邮箱的每个共享邮箱对应的一个 items[] 条目；
• password_included: false，作为明确的安全保证。

每个委派项都包含持久的 native_access_status/native_access_ready、folders 下的准确标准路径、服务器强制的 operations 以及有效的 send_as_ready/send_as_reason。can_send 仍表示管理员分配的可以回复权限；SMTP 不可用时它也可能是 true，因此自动化必须检查两个就绪字段。如果成员邮箱未激活、登录暂停或直接登录禁用，共享邮箱仍可发现，但其“发送身份”原因会返回 mailbox_unavailable、mailbox_login_suspended 或 direct_login_unavailable。旧版 folder 字段仍是准确的收件箱路径。请等到 native_access_ready=true 后再指导用户设置。

SMTP 会传输回复或转发邮件，但不会保存“已发送”副本。因此 sent_copy.smtp_saves_copy 为 false；请配置客户端将副本追加至 sent_copy.folder（与 folders.sent 相同），以便整个团队查看。客户端未自动映射“归档”或“垃圾邮件”时，folders.archive 和 folders.junk 是准确的移动目标。移至垃圾邮件文件夹本身并不保证训练服务器端分类器。

始终使用普通成员邮箱 ID 请求此 endpoint，并使用该成员自己的地址和密码验证客户端。不要创建第二个账户，也不要尝试使用共享地址直接验证。

原生访问禁用时，shared_mailboxes.native_access_enabled 为 false 且 items 为空。原生访问启用但 items 为空时，普通邮箱当前没有有效的共享邮箱成员资格。两种情况下都不会包含任何密码。

可选 lang 参数接受 Apple 描述文件 endpoint 所支持的相同 13 种语言。省略时，TrekMail 使用 Accept-Language，然后使用默认区域设置。每份指南都有稳定的 id、三个本地化 steps 和一个 action：use_server_settings 或 download_apple_profile。

connection_status=receiving_only 不代表完整设置成功。请先配置或恢复域名的出站路由，再指导用户连接会验证两台服务器的客户端。

connection_status=unavailable 表示邮箱生命周期已变化，无法再直接验证。请勿使用返回的服务器坐标或提供 Apple Mail 描述文件，而应刷新邮箱状态。

下载 Apple Mail 描述文件

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

响应是 .mobileconfig 附件。支持的 lang 值为 en、es、fr、de、pt、it、nl、ru、zh、ja、ko、ar 和 he。省略 lang 时，TrekMail 使用 Accept-Language，然后使用默认区域设置。

描述文件包含 IMAP 和 SMTP 设置，但没有密码字段。Apple 会在安装期间要求用户输入邮箱密码。出站邮件不可用时，TrekMail 返回 409 mail_client_setup_not_ready，而不会生成误导性描述文件。

MCP 工具

这些工具使用相同的 REST endpoints 和授权规则：

MCP 传输返回结构化工具内容，而非浏览器下载。将 content_base64 解码为字节并使用 file_name 保存；解码前不要将其重新解释为 JSON 或 UTF-8。

两个工具都要求托管 OAuth 权限范围 mail:read，它会扩展为内部 mailboxes:read。它们是只读工具，不依赖自托管 stdio 服务器中的任何破坏性操作环境标志。

错误

设置 endpoint 可能返回以下 sending.reason 值：mailbox_unavailable、direct_login_unavailable、domain_unavailable、domain_deprovisioning、account_suspended、email_verification_required、mailbox_sending_disabled、smtp_not_configured、managed_smtp_not_in_plan、managed_smtp_entitlement_inactive、smtp_profile_unavailable 或 smtp_route_invalid。