TaskPilots Mailbox Integration Documentation main README.md

title: Mailbox 外部集成文档

Mailbox 外部集成文档

这组文档面向 Mailbox 的外部对接方、集成方和客户端开发者，覆盖公开可用的接入能力、参数规范、认证方式、错误处理和联调要点。

当前公开能力：

  • HTTP API：适合系统集成收发、轮询消息、读取线程、上传附件
  • SMTP Submission 587：适合标准邮件客户端或程序化 SMTP 发信
  • MCP：适合 Agent / LLM / MCP 客户端以工具方式调用邮箱能力
  • SignalR：适合接收新邮件事件提示，再回到 HTTP API 拉取详情

当前不提供：

  • IMAP
  • POP3
  • Webhook 推送

接入前必读

默认情况下，HTTPS / MCP / SMTP STARTTLS 使用公网可信证书。

推荐接入路径

路径 A：业务系统收发邮件

适合：

  • 后端服务集成
  • 需要上传附件
  • 需要拉取消息详情与线程

阅读顺序：

  1. 快速开始
  2. 能力矩阵
  3. 认证与 scopes
  4. HTTP API 概览
  5. HTTP API 收发流程

路径 B：标准 SMTP 发信

适合：

  • 邮件客户端配置
  • 程序化 SMTP 发信
  • 只需要发信，不需要读信

阅读顺序：

  1. 快速开始
  2. TLS 与根证书
  3. 认证与 scopes
  4. SMTP Submission 概览
  5. SMTP 客户端配置

路径 C：Agent / MCP 工具调用

适合：

  • 模型工具调用
  • 远程 MCP 接入

阅读顺序：

  1. 快速开始
  2. TLS 与根证书
  3. MCP 集成

路径 D：实时事件提示

适合：

  • 收到新邮件后尽快补拉消息详情
  • 用“实时提示 + HTTP API”替代纯轮询

阅读顺序：

  1. 快速开始
  2. 认证与 scopes
  3. SignalR 新邮件事件

地址总览

  • HTTP API：https://mailbox.feinian.net
  • SignalR：https://mailbox.feinian.net/hubs/mailbox-events
  • MCP：https://mailbox.feinian.net/mcp
  • MCP 文档：https://mailbox.feinian.net/docs/mcp
  • MCP Manifest：https://mailbox.feinian.net/docs/mcp/server.json
  • fallback 根证书：https://mailbox.feinian.net/ca.crt
  • SMTP Submission：smtp.agent-mx.taskpilots.net:587

完整地址表见 公开地址与入口。

文档导航