title: Mailbox HTTP API 附件上传

Mailbox HTTP API 附件上传

公开附件上传采用“两步式”：

1. 先上传文件
2. 再在发信或回复时引用 attachmentUploadId

接口

• POST /api/messages/attachments

请求要求

• 认证：Authorization: Bearer <token>
• Content-Type：multipart/form-data
• 表单字段：
  • mailboxAddress
  • file

示例

curl -X POST https://mailbox.feinian.net/api/messages/attachments \
  -H "Authorization: Bearer <token>" \
  -F "mailboxAddress=support@example.com" \
  -F "file=@./quote.pdf"

成功响应

成功通常返回 201 Created，重点字段：

• attachmentUploadId

后续在发信或回复请求体中，把它放进：

• attachmentIds

权限要求

• token 需要 AttachmentWrite
• domain token 上传时通常必须显式传 mailboxAddress

常见失败

400 Bad Request

常见原因：

• multipart/form-data 不正确
• 缺少 mailboxAddress
• 缺少 file
• mailboxAddress 与当前 token 不匹配

401 Unauthorized

常见原因：

• 没带 token
• token 无效或过期

403 Forbidden

常见原因：

• 缺少 AttachmentWrite

推荐做法

• 先上传附件，再发信
• 上传成功后只保存 attachmentUploadId
• 不要假设 MCP 能代替附件上传，当前附件上传只开放给 HTTP API