title: Mailbox HTTP API 参考
Mailbox HTTP API 参考
这页汇总公开 HTTP API 的主要请求与响应字段。
默认情况下，下面列出的“响应字段”都位于统一返回包的 data 内，即响应体形如：
{
"data": {},
"code": 200,
"msg": null,
"errMsg": null,
"tid": "trace-id"
}
创建邮箱
POST /api/mailboxes
请求体：
address：邮箱地址，可直接指定完整地址displayName：显示名称domainId：可选localPart：可选notes：可选
data 内重点字段：
mailbox.mailboxIdmailbox.addressmailbox.displayNameinitialAccessTokeninitialAccessTokenIdinitialAccessTokenExpiresAtTs
消息列表
GET /api/messages
查询参数：
mailboxAddress：domain token场景通常必填limit：可选，默认100，最大200cursor：可选，传入上一页返回的nextCursordirection：可选，仅支持inbound或outbound
响应字段：
itemsnextCursortotalCount
items 内常见字段：
messageIdreceiptIdthreadIdmailboxIddirectionsubjectfromAddressfromDisplayNametoAddressmailboxAddressattachmentCountcreatedAtTsreceivedAtTssentAtTs
兼容说明：
GET /api/messages已从旧数组响应升级为分页对象响应- 旧解析逻辑必须改为读取
items nextCursor=null表示当前没有下一页
消息详情
`GET /api/messages/
在消息摘要字段基础上，还常见：
bodyTextbodyHtmlbodyFormatrawContentPathinReplyToMessageIdattachments
更新消息读状态
`PUT /api/messages/
请求体：
isRead
data 内重点字段：
messageIdisReadreadAtTs
批量更新消息读状态
POST /api/messages/bulk-read-state
请求体：
idsisRead
data 内重点字段：
requestedCountsucceededItemsfailedItems
删除单封消息
`DELETE /api/messages/
data 内重点字段：
messageIddeletedAtTsalreadyDeleted
批量删除消息
POST /api/messages/bulk-delete
请求体：
ids
data 内重点字段：
requestedCountsucceededItemsfailedItems
线程详情
`GET /api/threads/
响应字段：
threadIdmailboxIdsubjectcreatedAtTsmessages
发起新邮件
POST /api/messages/send
请求体：
mailboxAddresstoAddresssubjectbodyTextccAddressesbccAddressesattachmentIds
返回：
202 Accepted
回复邮件
`POST /api/messages/
请求体：
mailboxAddresssubjectbodyTextccAddressesbccAddressesattachmentIds
返回：
202 Accepted
上传附件
POST /api/messages/attachments
表单字段：
mailboxAddressfile
返回重点字段：
attachmentUploadId
Token 自助治理
GET /api/mailbox/access-tokens
返回列表字段常见包含：
tokenIdtokenNametokenPrefixscopescreatedSourceexpiresAtTsdisabledAtTslastUsedAtTslastUsedRemoteIpcanRevealPlaintextcreatedAtTs
POST /api/mailbox/access-tokens
请求体：
tokenNamescopesexpiresAtTs
响应字段：
tokenIdtokenNametokenPrefixscopescreatedSourceaccessTokenexpiresAtTscreatedAtTs