TaskPilots Mailbox Integration Documentation main concepts/auth-and-scopes.md

title: Mailbox 认证与 Scopes

Mailbox 认证与 Scopes

Mailbox 对外集成统一使用 access token 模型。

Token 类型

mailbox token

特点：

  • 绑定单个邮箱
  • 可用于 HTTP API
  • 可用于 MCP
  • 可用于 SMTP Submission 587

适合：

  • 单邮箱读信、发信、回复
  • 邮件客户端登录 SMTP

domain token

特点：

  • 绑定整个域
  • 可用于 HTTP API
  • 可用于 MCP
  • 可用于 SMTP Submission 587

适合：

  • 多邮箱统一集成
  • 域级系统对接

Scopes

公开集成常见 scopes：

  • MailboxRead：读取邮箱、消息和线程
  • MailboxRead 也用于 PUT /api/messages/{messageId}/read-state 与 POST /api/messages/bulk-read-state
  • MailboxSend：发送新邮件和回复
  • AttachmentWrite：上传出站附件
  • TokenManage：管理当前邮箱自己的后续 mailbox token
  • MailboxDelete：软删除消息
  • MailboxDelete 用于 DELETE /api/messages/{messageId} 与 POST /api/messages/bulk-delete
  • DomainManage：管理当前 domain token 所属域内 mailbox、密码和 mailbox token

第一个 token 怎么来

通过 POST /api/mailboxes 创建邮箱后，响应会直接返回 bootstrap token。

重点字段：

  • initialAccessToken
  • initialAccessTokenId
  • initialAccessTokenExpiresAtTs

建议：

  • 不要长期直接使用 bootstrap token
  • 尽快派生用途更清晰的后续 token

不同接入方式怎么带认证

HTTP API

使用：

  • Authorization: Bearer <token>

MCP

使用：

  • Authorization: Bearer <token>

SMTP Submission 587

使用标准 SMTP AUTH：

  • 用户名：任一 active sender identity 地址
  • 密码：mailbox token 或 domain token

限制：

  • token 必须具备 MailboxSend
  • mailbox token 只能代表自己的 mailbox
  • domain token 只能代表该 domain 下已存在且可解析到的 mailbox 主地址或 active alias

mailbox token 与 domain token 的差异

HTTP API

  • mailbox token 默认只操作绑定邮箱
  • domain token 在读信和发信时通常必须显式传 mailboxAddress
  • domain token 访问 /api/domain/* 时需要 DomainManage

MCP

  • mailbox token 可省略 mailboxAddress
  • domain token 调用 list_messages、send_mail、reply_message 时通常必须显式传 mailboxAddress

SignalR

  • mailbox token 可省略 mailboxAddress，省略时默认监听绑定邮箱
  • domain token 连接 /hubs/mailbox-events 时必须显式传 mailboxAddress
  • 单个 SignalR 连接只绑定一个 mailbox

SMTP

  • mailbox token 和 domain token 都可用于 SMTP
  • SMTP username 必须能解析到一个 active sender identity
  • domain token 的 SMTP username 还必须属于 token 自己的 domain

Token 自助治理

如果当前 mailbox token 具备 TokenManage，可以使用：

  • 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 的 scopes 必须是当前 token scopes 的子集
  • 新 token 过期时间不能晚于当前 token
  • domain token 不支持自助 TokenManage

密码换 token

公开第三方可以使用：

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

行为：

  • 传入 mailboxAddress + password
  • 成功时返回一个可直接用于 HTTP / MCP / SMTP 的 mailbox token
  • 如果当前邮箱已经存在符合默认集成 scope 集合的可 reveal token，则直接返回该 token
  • 否则自动创建一个新的默认 mailbox token 并返回

默认集成 scope 集合：

  • MailboxRead
  • MailboxSend
  • AttachmentWrite
  • TokenManage
  • MailboxDelete

Domain Token 域级治理

如果 domain token 具备 DomainManage，可以使用：

  • 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}

常见失败

401 Unauthorized

常见原因：

  • 没带 token
  • token 无效
  • token 已过期
  • token 已禁用

403 Forbidden

常见原因：

  • scope 不足
  • 例如缺少 MailboxSend 却去发信

SMTP 535 5.7.8 Authentication credentials invalid

常见原因：

  • 用户名不是邮箱地址
  • 密码不是有效的 mailbox token / domain token
  • token 不具备 MailboxSend
  • username 无法解析到 active sender identity
  • username 对当前 token 越权
  • username 不属于当前 domain token 的 domain

下一步