TrekMail REST API 开发者概览

TrekMail API 允许你通过 HTTP 客户端或 AI 代理管理域名、邮箱、转发、DNS、邮件迁移和网页邮箱操作。其中包括读取和发送邮件、草稿、定时发送、文件夹、联系人、日历、身份、模板和已阻止的发件人。经过认证的请求使用 bearer 令牌，响应采用 JSON 格式，API 活动会被审计。

你将获得的功能

• REST API v1，采用 JSON 请求和响应格式。
• **Bearer 令牌认证：**经过认证的 API 调用不使用 Cookie 或会话。
• 需要的写入操作使用幂等键，避免重试时重复执行操作。
• 按令牌限速，并提供 Retry-After 标头。
• 审计日志，可在控制面板的 AI Agents & API → Audit Log 下查看。
• MCP 服务器，其目录会根据当前连接的凭据、传输和安全设置进行筛选。因此，范围较窄的项目连接只会看到它可以使用的工具。
• **域名别名：**将辅助域名上仅用于接收的地址连接到主域名上的相同本地部分，并提供已保存与实时投递状态及安全删除功能。请参阅通过 API 和 MCP 使用域名别名。
• **双令牌架构：**基础设施使用独立的操作令牌，读取、发送、草稿、定时发送、联系人、日历、身份、模板和文件夹等完整邮件操作使用消息令牌。
• **出站送达率和退信洞察：**从控制面板获取已发送、已送达、硬退信和软退信汇总，以及每位收件人的 SMTP 代码和响应。请参阅送达率和退信。
• 邮箱存储用量：list_mailboxes 和 get_mailbox 返回 used_mb、quota_mb、allocation_mb 和 is_pooled，因此代理无需访问控制面板即可发现接近限额的邮箱。
• **White Label 管理：**检查设置、管理每个域名的品牌、邀请客户、控制角色和域名、暂停或恢复访问，并通过 API 或 MCP 查看活动。请参阅品牌指南和团队管理指南。

Drive API 和文件自动化

Drive 属于公共 API。它涵盖账户 Drive 和邮箱 Drive 空间、用量、文件夹浏览、上传、文件和文件夹管理、回收站、批量操作、公共共享链接、同步设备密码管理，以及只读的 Drive Storage Add-on 状态。

Drive 使用十一个操作令牌范围：drive:account:read、drive:account:write、drive:account:share、drive:account:purge、drive:mailbox:read、drive:mailbox:write、drive:mailbox:share、drive:mailbox:purge、drive:addon:read、drive:devices:read 和 drive:devices:write。Drive Add-on 的购买、调整容量和取消等计费操作仍只能在控制面板中完成，不会作为 API 或 MCP 写入操作开放。

请从 Drive API 概览或 Drive API 快速入门开始。

双令牌架构

API 使用两种相互独立的令牌类型。你可以根据需要使用其中一种或同时使用两种：

操作令牌和消息令牌拥有独立的范围和速率限制。通过在 MCP 服务器环境中配置两种令牌，同一个代理可以同时使用它们。

消息令牌适用于 Pro 和 Agency 套餐。

开始之前

• 所有套餐均可访问 API：
  • **Nano：**Email Verifier。添加 Drive Storage Add-on 后即可完整访问 Drive API 和 MCP。
  • **Starter：**完整的 Drive、完整的 Email Verifier，以及其余基础设施区域的只读访问权限。这些写入操作请使用控制面板。
  • **Pro / Agency：**完整的基础 API 访问权限，包括消息令牌。White Label 试用或付费附加组件生效期间会添加相应范围。
• **要连接 AI 代理？**在任何兼容客户端中将 https://trekmail.net/mcp 添加为远程 MCP 服务器。如果客户端支持浏览器授权，则不需要手动令牌。有关远程、CLI/桌面、桥接和自行托管选项，请参阅连接 AI 代理 (MCP)。
• **要构建自己的集成？**在 AI Agents & API → Tokens → Create token 下创建 tm_live_ 令牌，并将其作为 Authorization: Bearer … 发送。请参阅创建和管理 API 令牌。
• **初次使用 API？**单击 AI Agents & API 页面顶部的 Start tour，快速了解连接方式、令牌管理、已连接应用和审计日志。

认证工作方式

每个请求都必须在 Authorization 标头中包含令牌：

Authorization: Bearer tm_live_abc123...

操作令牌以 tm_live_ 开头，消息令牌以 tm_msg_ 开头。两者都只在创建时显示一次，之后无法再次查看。

如果令牌缺失、被撤销或已过期，API 将返回 401 和 unauthenticated 错误代码。

基础 URL 和版本控制

所有端点都位于：

https://trekmail.net/api/v1

基础 URL 显示在 AI Agents & API 控制面板的 Quick Reference 下。版本位于 URL 路径中。如果将来推出 v2，v1 仍将继续工作。

响应格式

成功响应返回 JSON；单个资源或分页列表使用 data 键：

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

错误响应采用一致的结构：

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

请求 ID

每个响应都包含 X-Request-Id 标头。你也可以通过请求中的 X-Request-Id 提供自己的值。该值会在响应中返回并记录到审计跟踪中。

速率限制

每个令牌每分钟都有速率限制。达到限制时，API 将返回 429，并在 Retry-After 标头中指明何时可以重试。

破坏性操作（删除意图）还具有每个令牌的额外每日限制，以及连续删除之间的冷却时间。

迁移写入操作（开始、取消、重试）具有每个令牌每分钟 10 个请求的专用速率限制，还受服务器级并发上限约束；全局运行的迁移过多时将返回 503。

消息令牌使用单独的限制。默认值为每个令牌每分钟 30 个读取请求、每分钟 60 个发送请求、每天 5,000 次成功读取，以及每个邮箱每天 100 次 API 发送。第二个发送安全计数器默认为每个令牌每天 500 次；通常先达到较低的邮箱上限。这些 API 保护措施不能替代套餐的托管 SMTP 限制或外部提供商自身的限制。

幂等性

标记为幂等的状态变更端点需要 Idempotency-Key 标头。这包括创建、更新、发送和删除操作，否则自动重试可能导致重复操作。提供商检测或连接测试等类似读取的 POST 操作不需要该标头；请检查端点表或 OpenAPI 规范。如果使用相同正文发送相同的键，API 会重放原始响应而不会创建重复项。

Idempotency-Key: create-mailbox-alice-2024

如果使用不同正文发送相同的键，API 将返回 409 Conflict。

邮箱存储分配

所有创建邮箱或邀请的端点，即 POST /api/v1/mailboxes、/api/v1/mailboxes:bulk、/api/v1/mailboxes/invites、/api/v1/mailboxes/invites:bulk，都接受可选整数 storage_allocation_mb。

分配会根据实时存储池减去现有专用邮箱和待处理专用邀请后的容量进行验证。批量端点还会验证整批分配的总和，如果会造成过度分配，则以 422 storage_pool_exceeded 拒绝整批操作。删除专用邮箱、兑换邀请（分配转移到新邮箱）或待处理邀请过期时，存储池都会刷新。

对于邀请，分配会记录在访问代码上，并在兑换时复制到新邮箱。如果兑换时存储池不再能容纳请求的分配（例如另一位管理员在此期间增加了专用分配），新邮箱会平稳降级为共享模式，而不会导致兑换失败；收件人会在成功页面上看到通知。

邮箱 Drive 访问权限

每个邮箱都有一个 drive_access 级别，用于决定其用户可在网页邮箱中使用多少 Drive 功能。该值会在邮箱资源中返回，可以使用 PATCH /api/v1/mailboxes/{id} 设置，也可以使用 POST /api/v1/mailboxes:drive-access 一次设置多个邮箱。

存储空间在整个账户中共享，因此此设置控制单个用户可以用文件占用多少存储池容量。

暂停邮箱登录

可以暂停邮箱登录，同时让它继续接收邮件：网页邮箱、IMAP、SMTP 和设备密码会被拒绝，已打开的会话会结束，但投递不受影响。因此不会退信，所有邮件都会等待登录恢复。使用 POST /api/v1/mailboxes/{id}:suspend-login（以及 :resume-login）进行设置，或使用 POST /api/v1/mailboxes:login-access 设置多个邮箱。

邮箱资源通过 login_suspended、login_suspended_at 和 login_suspended_reason 报告此状态。读取 login_suspended 以判断用户能否登录，读取 status 以判断邮箱本身是否运行。暂停登录的邮箱仍保持 active，因为它仍在接收邮件。:pause 是另一项操作：它会将 status 设置为 disabled，同时停止投递。

请参阅通过 API 暂停邮箱登录。

批量端点只接受 mailbox_ids、domain_id 或 all 中的一个选择器，并返回所执行的操作：

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

当一个域名对应一位客户时，应使用 domain_id 选择器。已处于所请求级别的邮箱计入 matched，但不计入 updated，因此可以安全地重复调用。

共享邮箱在单一端点上会以 422 drive_access_not_applicable 被拒绝，在批量端点上则会被跳过并计数：它们没有自己的网页邮箱用户，因此成员以自己的级别打开共享邮箱，存储在共享行上的值不会产生任何影响。

此限制同时适用于 API 和界面。受限邮箱的 Drive 空间不会出现在 GET /api/v1/drive/spaces 中，按 ID 访问其文件会返回 404，也无法为其创建设备同步。

转发地址

GET /api/v1/domains/{id}/forwarding-addresses 返回的不只是列表，因为转发地址的两个属性无法从地址本身看出：

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max 按域名计算并取决于套餐：Pro 为 100，Agency 为 300，Nano 或 Starter 可保存但不激活 25 个。
• delivery.active 表示这些规则此刻是否正在转发邮件。套餐低于 requires_plan 时为 false，设置 paused_until 时也为 false（账户超过了每小时发送速率；请参阅各套餐的发送限制）。规则可以是 is_active: true 但仍不投递，因此在报告转发功能正常之前，请读取 delivery，而不只是 is_active。

在无法投递的套餐上也允许创建并返回 201：规则会被保存，并在升级后开始工作。这与控制面板一致，其中此类规则显示为已保存但未激活。

拒绝会以 422 返回，且 error.code 设置为 validation_error 或 limit_exceeded。原因可能是地址已在域名上使用、收件人与发件人在同一域名（会形成循环）、收件人域名没有有效的 MX，或每个域名的限额已满。

这些端点上的 POST 和 DELETE 需要 Idempotency-Key；PATCH 不需要。

投递历史记录

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log 返回近期邮件的实际处理结果，最新事件排在最前：

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome 可以是 delivered、deferred（临时失败，仍在重试）、failed（收件人的服务器拒绝了邮件）或 blocked。最后一种表示垃圾邮件过滤器在转发之前阻止了邮件，因此它根本没有到达收件人。将 blocked 当作退信会让人错误地调查接收服务器，而问题实际发生在我们的服务器上。

limit（1-200，默认 100）是唯一的参数。窗口取决于套餐的保留期：Agency 为 30 天，其他套餐为 7 天。没有更早的事件可供查询，因为转发事件会被清除。

共享（团队）邮箱

共享邮箱是 support@ 或 sales@ 之类的团队收件箱，成员通过自己的普通邮箱账户在 Webmail 中打开它；启用原生访问后，也可将其作为委托的 IMAP 文件夹打开。它没有共享密码或单独登录。访问权限是扁平的：每位成员都可以读取，一个 can_send 标志控制该成员能否以此地址回复（true）或只能读取（false）。没有成员角色。

GET /api/v1/mailboxes 和 GET /api/v1/mailboxes/{id} 现在返回 mailbox_type（"user" 或 "shared"）以及布尔值 is_shared；共享邮箱还包括 shared_member_count。调用成员端点之前，请使用这些字段区分团队收件箱和普通邮箱。

成员端点复用现有的 mailboxes:read / mailboxes:write 范围。共享邮箱没有单独的范围。

要了解原生邮件应用访问，请为普通成员邮箱调用 GET /api/v1/mailboxes/{member_mailbox_id}/client-setup。其 shared_mailboxes 对象会报告持久的原生就绪状态、有效的 Send As 就绪状态和原因、Inbox/Sent/Archive/Junk 的确切路径以及允许的操作。can_send 是分配的 Can reply 权限，并不能证明 SMTP 当前已就绪。该端点绝不会返回密码。使用共享邮箱 ID 调用它会返回 422 direct_login_unavailable，因为共享地址无法直接进行认证。

删除成员、更改 can_send 或将共享邮箱转换为普通邮箱时，如果启用了原生访问，则会同步邮件服务器权限。503 native_access_sync_failed 响应可以重试，并保证成员关系、权限或邮箱类型保持不变，而不是仅部分应用操作。

可用端点

Drive 有单独的参考文档，此处不再重复；请参阅 Drive API 概览。为向后兼容而保留的账户级 SMTP 端点在每个域名的 SMTP 路由下说明，而不作为当前端点列出。

Cloudflare 端点遵循与控制面板相同的流程：验证令牌、列出区域、连接域名、预览 DNS 更改，然后应用更改。/cloudflare/preview 和 /cloudflare/apply 都接受两个可选的每域名控制项：

• included_records 是允许修改的记录列表，以域名 ID 为键：{ "123": ["mx_primary", "spf_record"] }。省略的记录会被跳过，因此可以只应用 MX 和 SPF，稍后再处理 DKIM。省略此字段即可应用所有记录。
• confirmed_conflicts：当预览标记已存在但值不同的记录时，请在此列出其记录 ID（使用相同的 { domain_id: [record_ids] } 结构），以授权替换。

记录 ID（mx_primary、spf_record、dkim_primary、dmarc_main、…）直接来自预览响应，因此典型代理会先调用预览，然后将需要的 ID 传回 apply：

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

每个域名的 SMTP 路由和账户默认值

SMTP 按域名配置。每个域名可选择三种路由之一：平台托管发送、已保存的 SMTP 配置文件（你自己的提供商，可跨域名复用）或“未配置”。一个账户级默认值决定新域名最初使用哪种路由。

每域名端点（smtp:read / smtp:write）：

关于路由正文的几点说明：

• smtp_mode=platform 选择托管发送；smtp_mode=profile 需要 smtp_connection_id；not_configured 清除路由。
• smtp_mode=inherit 使域名实时跟随账户默认值：默认值改变时，该域名也随之改变。网页界面始终写入具体路由，但后端仍支持 inherit，因此 GET 返回 effective_smtp_mode，显示 inherit 当前解析到的值。
• set_account_default: true 相当于控制面板中的 Make this the account default 开关（新域名从此路由开始）。apply_to_all: true 相当于 Apply to all domains 按钮（一次性将每个域名切换到此路由）。

账户级默认端点（smtp:read / smtp:write）：

删除作为账户默认值的配置文件会将默认值重置为套餐基准。

旧版端点。账户级 GET/PUT /api/v1/smtp（以及 DELETE /api/v1/smtp/{id}、POST /api/v1/smtp:test、GET /api/v1/smtp:test-status/{jobId}）为向后兼容而保留，但不再控制每域名路由：请使用上述每域名端点和 /smtp/default。旧版 MCP 工具 get_smtp_config / update_smtp_config 也因此被弃用。

White Label 品牌、客户和团队访问

品牌通过 branding:read / branding:write 按域名配置。域名可以使用自己的品牌（mode=custom）、继承账户默认值（mode=inherit）或关闭品牌。需要有效的 White Label 试用或付费附加组件。取消后，所有者在显示的宽限期内保留只读恢复权限。读取域名的 dns_records 并准确发布返回的记录。不要根据示例推导主机名或 CNAME 目标。

PATCH 是部分合并，因此省略的字段会保留。如果品牌当前关闭，请传递 mode 以重新启用。自定义 sender_email 必须位于具有已验证 DKIM 密钥的域名上。mail_zone_enabled 在品牌自己的域名下提供邮件应用和 DAV 同步。它属于品牌而非单个域名，因此需要 mode=custom 或 scope=account_default；inherit 域名返回 422 inherited_brand。读取 mail_zone.dns_status、mail_zone.client_hosts_status、mail_zone.records、mail_zone.dav_url 和 mail_zone.dav_ready 以跟踪配置，并且只使用已就绪的 DAV 地址。完整代理工作流程请参阅 White Label 品牌 API 和 MCP 指南。

账户级 White Label 界面在 /api/v1/white-label 下增加 13 条路由：状态和设置进度、实时访问目录、成员列表和生命周期操作、账户活动，以及每位成员的操作和登录历史记录。它使用 members:read、members:write 和 activity:read。访问权限始终是账户权益、用户当前成员资格、凭据授权和任何域名限制的交集。路由表和状态转换请参阅通过 API 和 MCP 管理 White Label 团队。

OpenAPI 规范位于 /api/openapi.json，可导入 Postman、Insomnia 或代码生成器。

快速修复

• **401 “unauthenticated”：**检查是否存在 Authorization: Bearer <token> 标头，并确认令牌未被撤销或过期。
• **403 “plan_api_disabled”：**请求的范围不在你的套餐中。Nano 包含 Email Verifier（购买 Drive Storage Add-on 后也包含 Drive）。其余 API 需要升级到 Starter 或更高套餐。
• **403 “token_scope_blocked_by_plan”：**令牌包含当前套餐不可用的范围。撤销该令牌，并使用允许的范围创建新令牌。
• **403 “scope_blocked_by_entitlement”：**由于附加组件未激活，或操作是在宽限期内执行写入，已保存的 White Label 授权不可用。重新激活 White Label，然后重新签发或授权凭据。
• **403 “scope_blocked_by_membership”：**当前成员角色比请求的操作范围更窄。请所有者更改角色；仅重新授权无法扩大成员资格。
• **422 “missing_idempotency_key”：**向端点参考中指定的写入操作添加 Idempotency-Key 标头。
• **403 “mailbox_sending_paused”：**该邮箱的出站邮件不再像其所有者发送的邮件，通常是密码落入他人手中，因此已停止发送。读取、列出和其他所有端点仍可使用；只有发送被拒绝，重试不会解除限制。需要更改邮箱密码，之后由支持团队重新启用发送。请参阅为什么我无法发送电子邮件？。
• **429 速率受限：**等待 Retry-After 标头中指定的时长后再重试。

发送电子邮件：正文、标头和送达率

POST /api/v1/messages/send 接受请求结构 {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}。

• body.text 和 body.html 都是可选的，但至少需要一个。如果只提供 body.text，我们会使用 <p> 段落自动生成 HTML 替代版本（空行分隔段落；单个换行变为 <br>），使邮件在所有现代客户端中正常显示。如需等宽文本，请在 body.html 中发送字面值 <pre>...</pre>。
• headers 是用户提供的可选出站标头对象。允许列表包括 List-Unsubscribe、List-Unsubscribe-Post、Reply-To 和任何自定义 X-* 跟踪标头。其他名称（From、Subject、Message-Id、Authentication-Results 等）由平台管理，并以 422 拒绝。包含 CR/LF 的值也会被拒绝（防止标头注入）。根据 RFC 2822，每个值最多 998 个字符。
• 对于批量发送或自动化场景，请参阅批量发件人送达率标头部分，了解 List-Unsubscribe 设置和账户级 auto_list_unsubscribe 开关。