QQ 邮箱

QQ Mail

授权码认证、有限 INBOX 索引、按需正文、精确已读与受控 SMTP 发信。

Authorization-code authentication, bounded INBOX indexing, on-demand bodies, exact Seen writes, and controlled SMTP sending.

本分类共 13 个端点。返回 完整 API 索引 或 API 架构与安全说明。

GET /api/qq-mail/accounts

列出 QQ 邮箱账号 / List QQ Mail accounts

返回当前用户的脱敏账号与同步状态，不返回授权码或密文。

Return sanitized accounts and synchronization state without authorization codes or ciphertext.

cURL 示例

curl --request GET \
  --url "https://mail.example.com/api/qq-mail/accounts" \
  --header "Authorization: Bearer om_at_..."

POST /api/qq-mail/accounts

连接 QQ 邮箱账号 / Connect a QQ Mail account

验证个人 @qq.com 邮箱的授权码后，用独立密钥加密保存并请求首次同步。

Validate an authorization code for a personal @qq.com mailbox, encrypt it with a dedicated key, and request the initial sync.

注意：authorizationCode 必须是 QQ 邮箱生成的授权码，不是 QQ 登录密码。

Note: authorizationCode must be generated by QQ Mail; never submit the QQ account password.

cURL 示例

curl --request POST \
  --url "https://mail.example.com/api/qq-mail/accounts" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Personal QQ Mail",
  "email": "123456789@qq.com",
  "authorizationCode": "qq-mail-authorization-code"
}'

PATCH /api/qq-mail/accounts/{id}

重命名 QQ 邮箱账号 / Rename a QQ Mail account

修改当前用户 QQ 邮箱账号的本地显示名称。

Change the local display name of a QQ Mail account owned by the current user.

cURL 示例

curl --request PATCH \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Personal QQ"
}'

PUT /api/qq-mail/accounts/{id}/authorization-code

更新 QQ 邮箱授权码 / Update a QQ Mail authorization code

先验证新授权码，再替换密文；验证失败时保留原凭据。

Validate the new authorization code before replacing ciphertext; preserve the existing credential if validation fails.

cURL 示例

curl --request PUT \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id/authorization-code" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "authorizationCode": "replacement-authorization-code"
}'

DELETE /api/qq-mail/accounts/{id}

断开 QQ 邮箱账号 / Disconnect a QQ Mail account

级联删除本地密文和元数据索引，不删除远端邮件或代为撤销授权码。

Cascade-delete local ciphertext and metadata without deleting remote mail or revoking the authorization code.

cURL 示例

curl --request DELETE \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id" \
  --header "Authorization: Bearer om_at_..."

POST /api/qq-mail/accounts/{id}/verify

验证 QQ 邮箱连接 / Verify a QQ Mail connection

使用已保存授权码重新执行只读 QQ IMAP 登录与 EXAMINE。

Use the saved authorization code to run read-only QQ IMAP login and EXAMINE again.

cURL 示例

curl --request POST \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id/verify" \
  --header "Authorization: Bearer om_at_..."

POST /api/qq-mail/accounts/{id}/sync

请求 QQ 邮箱同步 / Request QQ Mail synchronization

在频率限制和账号租约保护下，把有限 INBOX 同步任务加入 Queue。

Queue a bounded INBOX synchronization under rate limiting and an account lease.

cURL 示例

curl --request POST \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id/sync" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "limit": 20
}'

POST /api/qq-mail/accounts/{id}/identities

添加 QQ 邮箱发信身份 / Add a QQ Mail sender identity

使用账号现有授权码验证候选地址可登录固定 QQ SMTP 后，保存为可选发信身份。

Use the account’s existing authorization code to verify that the candidate address can sign in to the fixed QQ SMTP service before saving it as an optional sender identity.

注意：只接受 @qq.com、@foxmail.com 与 @vip.qq.com；验证过程不会发送测试邮件。

Note: Only @qq.com, @foxmail.com, and @vip.qq.com are accepted; verification does not send a test message.

cURL 示例

curl --request POST \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id/identities" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Foxmail address",
  "email": "name@foxmail.com"
}'

DELETE /api/qq-mail/accounts/{id}/identities/{identityId}

删除 QQ 邮箱发信身份 / Delete a QQ Mail sender identity

删除当前账号的非主发信身份，不影响共享 INBOX、远端邮箱或主身份。

Delete a non-primary sender identity from the current account without affecting the shared INBOX, remote mailbox, or primary identity.

cURL 示例

curl --request DELETE \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id/identities/:identityId" \
  --header "Authorization: Bearer om_at_..."

GET /api/qq-mail/messages

列出 QQ 邮箱聚合邮件 / List unified QQ Mail messages

按账号或全部账号搜索 D1 元数据索引，并使用稳定游标分页。

Search the D1 metadata index for one or all accounts with stable cursor pagination.

cURL 示例

curl --request GET \
  --url "https://mail.example.com/api/qq-mail/messages?limit=30" \
  --header "Authorization: Bearer om_at_..."

POST /api/qq-mail/accounts/{id}/messages

发送或回复 QQ 邮件 / Send or reply with QQ Mail

从当前用户已连接的 QQ 地址，通过固定官方 SMTP 端点异步发送单收件人邮件。

Asynchronously send a single-recipient message from the current user’s connected QQ address through the fixed official SMTP endpoint.

注意：replyToMessageId 存在时，服务端从原邮件推导收件人、主题和线程头，忽略客户端伪造值。

Note: When replyToMessageId is present, the server derives the recipient, subject, and thread headers from the original message and ignores spoofed client values.

注意：sender 必须是该账号中已通过 QQ SMTP 验证的身份；省略时使用主身份。

Note: sender must be an identity verified by QQ SMTP for this account; omit it to use the primary identity.

注意：DATA 提交后的超时或断连会标记为投递结果不确定，不会自动重发。

Note: A timeout or disconnect after DATA is marked delivery-uncertain and is never retried automatically.

cURL 示例

curl --request POST \
  --url "https://mail.example.com/api/qq-mail/accounts/resource_id/messages" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "to": "recipient@example.com",
  "subject": "Hello",
  "text": "Message body",
  "idempotencyKey": "request_12345678"
}'

GET /api/qq-mail/accounts/{accountId}/messages/{messageId}

读取 QQ 邮箱正文 / Read a QQ Mail message

重新校验归属与 UIDVALIDITY，通过 BODY.PEEK[] 按需读取正文，并独立尝试写入 Seen。

Revalidate ownership and UIDVALIDITY, fetch the body on demand with BODY.PEEK[], and independently attempt a Seen write.

注意：已读写入失败不会阻断正文响应；移动、删除、归档、星标和其他远端写入均未开放。

Note: A Seen write failure does not block the body response; move, delete, archive, star, and other remote writes are not available.

cURL 示例

curl --request GET \
  --url "https://mail.example.com/api/qq-mail/accounts/qq_mail_account_id/messages/message_id" \
  --header "Authorization: Bearer om_at_..."

GET /api/qq-mail/accounts/{accountId}/messages/{messageId}/attachments/{partId}

下载 QQ 邮箱附件 / Download a QQ Mail attachment

校验归属后按需读取并返回不超过 5 MiB 的附件。

Verify ownership, then fetch and return an attachment up to 5 MiB on demand.

cURL 示例

curl --request GET \
  --url "https://mail.example.com/api/qq-mail/accounts/qq_mail_account_id/messages/message_id/attachments/0" \
  --header "Authorization: Bearer om_at_..." \
  --output "qq-mail-attachment.bin"