TaskPilots Mailbox Integration Documentation main realtime/signalr-events.md

title: Mailbox SignalR 新邮件事件

Mailbox SignalR 新邮件事件

SignalR 用于“新邮件事件提示”，不替代消息读取接口。

地址

  • https://mailbox.feinian.net/hubs/mailbox-events

鉴权方式

连接时使用：

  • access_token=<mailbox token 或 domain token>

单邮箱监听参数

连接参数：

  • mailboxAddress=<目标邮箱地址>

参数语义固定为：

  • mailbox token 可省略 mailboxAddress；省略时默认监听绑定邮箱
  • mailbox token 显式传入 mailboxAddress 时，必须与绑定邮箱一致
  • domain token 必须显式传入 mailboxAddress
  • 单个连接只绑定一个 mailbox；如果要同时监听多个邮箱，需要建立多个连接

示例：

https://mailbox.feinian.net/hubs/mailbox-events?access_token=<mailbox-token>

https://mailbox.feinian.net/hubs/mailbox-events?access_token=<mailbox-token>&mailboxAddress=support@example.com

https://mailbox.feinian.net/hubs/mailbox-events?access_token=<domain-token>&mailboxAddress=support@example.com

事件名

  • messageReceived

事件字段

事件常见字段：

  • messageId
  • threadId
  • mailboxId
  • mailboxAddress
  • domainId
  • domainName
  • direction
  • subject
  • fromAddress
  • toAddress
  • inboundRouteType
  • receivedAtTs
  • occurredAtTs

使用方式

推荐流程：

  1. 用 access_token 和可选/必选的 mailboxAddress 连接 SignalR Hub
  2. 监听 messageReceived
  3. 收到事件后先调用 GET /api/messages?mailboxAddress=<当前监听邮箱>&limit=100
  4. 从分页对象里读取 items，必要时继续使用 nextCursor
  5. 再按需调用 GET /api/messages/{messageId} 或 GET /api/threads/{threadId}

重要限制

  • 事件只表示“有新邮件提示”
  • 事件不是唯一真相源
  • 事件不包含完整正文与线程全文
  • 连接断开、重连成功或客户端重启后，必须带同样的连接参数重新建立连接并主动补拉

配合使用