title: Mailbox HTTP API 收发流程

Mailbox HTTP API 收发流程

这页按“创建邮箱 → 确认可见邮箱 → 收信 → 发信 → 回复”的顺序说明典型调用方式。

1. 创建邮箱并拿到 bootstrap token

curl -X POST https://mailbox.feinian.net/api/mailboxes \
  -H "Content-Type: application/json" \
  -d '{
    "address": "support@example.com",
    "displayName": "Support"
  }'

重点字段：

mailbox.mailboxId
mailbox.address
initialAccessToken
initialAccessTokenId
initialAccessTokenExpiresAtTs

说明：

这个入口不要求先带 token
创建成功后会直接返回 bootstrap token

2. 查看当前可见邮箱

curl https://mailbox.feinian.net/api/mailboxes \
  -H "Authorization: Bearer <token>"

语义：

mailbox token 返回绑定邮箱
domain token 返回域下可见邮箱列表

3. 拉取消息列表

curl "https://mailbox.feinian.net/api/messages?mailboxAddress=support@example.com&limit=100" \
  -H "Authorization: Bearer <token>"

重要说明：

GET /api/messages 现在返回分页对象：items、nextCursor、totalCount
默认 limit=100，最大 limit=200
继续拉下一页时，把上一次返回的 nextCursor 作为新的 cursor
可选 direction=inbound 或 direction=outbound
domain token 必须显式传 mailboxAddress
这是 breaking change：旧数组响应已废弃

4. 读取单封消息

curl https://mailbox.feinian.net/api/messages/REPLACE_MESSAGE_ID \
  -H "Authorization: Bearer <token>"

常见字段：

messageId
threadId
direction
subject
fromAddress
toAddress
bodyText
attachments
inReplyToMessageId

5. 读取完整线程

curl https://mailbox.feinian.net/api/threads/REPLACE_THREAD_ID \
  -H "Authorization: Bearer <token>"

适合：

回复前还原上下文
一次拉完整线程消息

6. 标记消息已读或未读

curl -X PUT https://mailbox.feinian.net/api/messages/REPLACE_MESSAGE_ID/read-state \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "isRead": true
  }'

说明：

isRead: true 表示标记已读
isRead: false 表示恢复未读
domain token 不需要额外传 mailboxAddress，只要该消息属于可见 mailbox

7. 批量更新读状态

curl -X POST https://mailbox.feinian.net/api/messages/bulk-read-state \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["message-a", "message-b"],
    "isRead": true
  }'

说明：

单次最多 10000 个消息 ID
返回 succeededItems 与 failedItems
允许部分成功

8. 软删除单封消息

curl -X DELETE https://mailbox.feinian.net/api/messages/REPLACE_MESSAGE_ID \
  -H "Authorization: Bearer <token>"

说明：

删除后该消息不会再出现在 public list/detail/thread 可见结果中
重复删除同一条消息会返回幂等成功，并标记 alreadyDeleted

9. 批量软删除消息

curl -X POST https://mailbox.feinian.net/api/messages/bulk-delete \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["message-a", "message-b"]
  }'

说明：

单次最多 10000 个消息 ID
返回 succeededItems 与 failedItems
已删除消息会在成功项中返回 alreadyDeleted: true

10. 发起新邮件

curl -X POST https://mailbox.feinian.net/api/messages/send \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mailboxAddress": "support@example.com",
    "toAddress": "user@example.net",
    "subject": "Hello",
    "bodyText": "Hi from Mailbox.",
    "ccAddresses": [],
    "bccAddresses": [],
    "attachmentIds": []
  }'

说明：

成功返回 202 Accepted
表示消息已入队
不表示远端邮箱已签收
domain token 通常必须显式传 mailboxAddress

11. 回复已有邮件

curl -X POST https://mailbox.feinian.net/api/messages/REPLACE_MESSAGE_ID/reply \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mailboxAddress": "support@example.com",
    "subject": "Re: Hello",
    "bodyText": "Thanks for your message.",
    "ccAddresses": [],
    "bccAddresses": [],
    "attachmentIds": []
  }'

重要约束：

回复时 mailboxAddress 必须与父消息所属邮箱一致
domain token 也必须显式传 mailboxAddress

轮询建议

因为当前没有 webhook，推荐这样处理：

初次启动先全量拉取最近消息
本地按 messageId 去重
优先按 receivedAtTs 排序
高频邮箱提高轮询频率，避免最近窗口被覆盖

实时提示场景可配合：

SignalR 新邮件事件