TaskPilots Mailbox Integration Documentation main quickstart.md

title: Mailbox 外部集成快速开始

Mailbox 外部集成快速开始

这份快速开始帮助你用最短路径完成首次联通。

第一步：确认 TLS 形态

默认目标是公网可信证书：

  • 标准 HTTPS / MCP / SMTP STARTTLS 客户端通常不需要额外导入根证书
  • 如果值班口径明确说当前处于 fallback 自签名模式，再按 TLS 与根证书 导入 https://mailbox.feinian.net/ca.crt

第二步：选接入方式

用 HTTP API 做收发

适合：

  • 业务系统直连
  • 需要读信、拉线程、上传附件

最短路径：

  1. 调用 POST /api/mailboxes 创建邮箱并拿到 bootstrap token
  2. 调用 GET /api/mailboxes 确认当前 token 可见邮箱
  3. 调用 GET /api/messages 拉取消息分页（读取 items / nextCursor / totalCount）
  4. 调用 POST /api/messages/send 或 POST /api/messages/{messageId}/reply 发信

继续阅读：

用 SMTP Submission 做标准发信

适合：

  • 邮件客户端
  • 程序化 SMTP 发信

最短路径：

  1. 准备一个具备 MailboxSend 的 mailbox token 或 domain token
  2. 连接 smtp.agent-mx.taskpilots.net:587
  3. 启用 STARTTLS
  4. 用 username = active sender identity 地址、password = mailbox token / domain token 做认证

补充约束：

  • username 必须是已存在且可解析的 mailbox 主地址或 active alias
  • 如果使用 domain token，username、MAIL FROM 和 MIME From 都必须落在该 token 自己的 domain
  • 不支持使用同域任意未注册地址发信

继续阅读：

用 MCP 做工具式接入

最短路径：

  1. 准备 mailbox token 或 domain token
  2. 配置远程服务地址为 https://mailbox.feinian.net/mcp
  3. 带上 Authorization: Bearer <token>
  4. 先调用 list_mailboxes

继续阅读：

用 SignalR 做实时事件提示

最短路径：

  1. 准备 mailbox token 或 domain token
  2. 用单邮箱监听参数连接 https://mailbox.feinian.net/hubs/mailbox-events
  3. 监听 messageReceived
  4. 收到事件后回到 HTTP API 拉分页列表或单封详情

连接示例：

  • mailbox token 默认监听自身邮箱： https://mailbox.feinian.net/hubs/mailbox-events?access_token=<mailbox-token>
  • domain token 必须显式指定目标邮箱： https://mailbox.feinian.net/hubs/mailbox-events?access_token=<domain-token>&mailboxAddress=support@example.com

继续阅读：

第三步：确认参数口径

固定公开地址：

  • HTTP API：https://mailbox.feinian.net
  • SMTP Submission：smtp.agent-mx.taskpilots.net:587
  • fallback 根证书：https://mailbox.feinian.net/ca.crt

统一参数规范：