TaskPilots Mailbox Integration Documentation main http-api/overview.md

title: Mailbox HTTP API 概览

Mailbox HTTP API 概览

HTTP API 是公开集成的主路径，适合系统级收发、轮询收信、读取线程、上传附件、密码换 token 和域级 token 治理。

基址

  • https://mailbox.feinian.net

前置条件

  1. 客户端已经信任根证书
  2. 你已经准备好 mailbox token 或 domain token，或准备通过邮箱密码换取 mailbox token
  3. 你已经明确是否需要附件上传或 token 自助治理

相关文档：

认证方式

除 POST /api/mailboxes 和 POST /api/mailbox/auth/login/password 外，公开接口统一使用：

  • Authorization: Bearer <token>

统一响应契约

所有业务 JSON HTTP API 默认返回统一包：

{
  "data": {},
  "code": 200,
  "msg": null,
  "errMsg": null,
  "tid": "trace-id"
}

约定：

  • 成功时从 data 读取业务数据
  • 失败时从 code、msg、errMsg、tid 读取错误与诊断信息
  • JSON 字段统一 camelCase
  • 时间字段统一毫秒 Unix timestamp，例如 createdAtTs

公开接口

  • POST /api/mailboxes
  • POST /api/mailbox/auth/login/password
  • GET /api/mailboxes
  • GET /api/domain/mailboxes
  • POST /api/domain/mailboxes
  • POST /api/domain/mailboxes/{mailboxId}/password
  • GET /api/domain/mailboxes/{mailboxId}/access-tokens
  • POST /api/domain/mailboxes/{mailboxId}/access-tokens
  • POST /api/domain/mailboxes/{mailboxId}/access-tokens/{tokenId}/reveal
  • POST /api/domain/mailboxes/{mailboxId}/access-tokens/{tokenId}/disable
  • DELETE /api/domain/mailboxes/{mailboxId}/access-tokens/{tokenId}
  • GET /api/messages
  • GET /api/messages/{messageId}
  • PUT /api/messages/{messageId}/read-state
  • POST /api/messages/bulk-read-state
  • DELETE /api/messages/{messageId}
  • POST /api/messages/bulk-delete
  • GET /api/threads/{threadId}
  • POST /api/messages/send
  • POST /api/messages/{messageId}/reply
  • POST /api/messages/attachments
  • GET /api/mailbox/access-tokens
  • POST /api/mailbox/access-tokens
  • POST /api/mailbox/access-tokens/{tokenId}/reveal
  • POST /api/mailbox/access-tokens/{tokenId}/disable
  • DELETE /api/mailbox/access-tokens/{tokenId}

典型能力

收信与读取

适用接口：

  • GET /api/messages
  • GET /api/messages/{messageId}
  • PUT /api/messages/{messageId}/read-state
  • POST /api/messages/bulk-read-state
  • DELETE /api/messages/{messageId}
  • POST /api/messages/bulk-delete
  • GET /api/threads/{threadId}

发信与回复

适用接口：

  • POST /api/messages/send
  • POST /api/messages/{messageId}/reply

附件上传

适用接口：

  • POST /api/messages/attachments

Token 自助治理

适用接口：

  • GET /api/mailbox/access-tokens
  • POST /api/mailbox/access-tokens
  • POST /api/mailbox/access-tokens/{tokenId}/reveal
  • POST /api/mailbox/access-tokens/{tokenId}/disable
  • DELETE /api/mailbox/access-tokens/{tokenId}

密码换 token

适用接口：

  • POST /api/mailbox/auth/login/password

域级治理

适用接口：

  • GET /api/domain/mailboxes
  • POST /api/domain/mailboxes
  • POST /api/domain/mailboxes/{mailboxId}/password
  • GET /api/domain/mailboxes/{mailboxId}/access-tokens
  • POST /api/domain/mailboxes/{mailboxId}/access-tokens
  • POST /api/domain/mailboxes/{mailboxId}/access-tokens/{tokenId}/reveal
  • POST /api/domain/mailboxes/{mailboxId}/access-tokens/{tokenId}/disable
  • DELETE /api/domain/mailboxes/{mailboxId}/access-tokens/{tokenId}

mailbox token 与 domain token 的差异

mailbox token

  • 默认只绑定一个邮箱
  • 调用时通常可以省略 mailboxAddress
  • 如果显式传 mailboxAddress，必须与绑定邮箱一致

domain token

  • 可以访问一个域下的多个邮箱
  • 读信和发信时通常必须显式传 mailboxAddress
  • 具备 DomainManage 时可以治理该域下 mailbox、密码和 mailbox token

平台语义

  • POST /api/messages/send 与 reply 返回 202 Accepted，表示请求已入队
  • PUT /api/messages/{messageId}/read-state 用于设置已读或未读
  • DELETE /api/messages/{messageId} 与 POST /api/messages/bulk-delete 都是软删除
  • 202 不表示远端邮箱已经签收
  • GET /api/messages 现在返回 cursor 分页对象，固定包含 items、nextCursor、totalCount
  • 公开 HTTP 列表使用 cursor + limit + direction；默认 limit=100，最大 200
  • 这是 breaking change：旧数组响应已废弃，接入方必须改为从 items 读取列表项

下一步