Gmail 聚合收件箱

Gmail unified inbox

多账号凭据、受控 IMAP 同步、聚合索引、正文与附件。

Multi-account credentials, controlled IMAP synchronization, unified indexing, message bodies, and attachments.

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

GET /api/gmail/accounts

列出 Gmail 账号 / List Gmail accounts

返回当前用户的脱敏 Gmail 账号和同步状态，不返回凭据或密文。

Return the current user’s sanitized Gmail accounts and sync state without credentials or ciphertext.

cURL 示例

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

POST /api/gmail/accounts

连接 Gmail 账号 / Connect a Gmail account

验证固定 Gmail IMAP 端点后，用独立密钥加密保存应用专用密码。

Validate the fixed Gmail IMAP endpoint, then encrypt the app password with a dedicated key.

注意：只接受 Google 生成的 16 位应用专用密码；不要提交 Google 账号主密码。

Note: Only a Google-generated 16-character app password is accepted; never submit the Google Account password.

cURL 示例

curl --request POST \
  --url "https://mail.example.com/api/gmail/accounts" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Personal Gmail",
  "email": "owner@gmail.com",
  "appPassword": "xxxx xxxx xxxx xxxx"
}'

PATCH /api/gmail/accounts/{id}

重命名 Gmail 账号 / Rename a Gmail account

修改当前用户 Gmail 账号的显示名称。

Change the display name of a Gmail account owned by the current user.

cURL 示例

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

PUT /api/gmail/accounts/{id}/app-password

更新 Gmail 应用密码 / Update a Gmail app password

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

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

cURL 示例

curl --request PUT \
  --url "https://mail.example.com/api/gmail/accounts/resource_id/app-password" \
  --header "Authorization: Bearer om_at_..." \
  --header "Content-Type: application/json" \
  --data '{
  "appPassword": "xxxx xxxx xxxx xxxx"
}'

DELETE /api/gmail/accounts/{id}

断开 Gmail 账号 / Disconnect a Gmail account

级联删除本地凭据和元数据索引，不会撤销 Google 端应用密码。

Cascade-delete local credentials and metadata without revoking the Google-side app password.

cURL 示例

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

POST /api/gmail/accounts/{id}/verify

验证 Gmail 连接 / Verify a Gmail connection

使用已保存凭据重新执行只读 Gmail IMAP 登录与 EXAMINE。

Use the saved credential to run read-only Gmail IMAP login and EXAMINE again.

cURL 示例

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

POST /api/gmail/accounts/{id}/sync

请求 Gmail 同步 / Request Gmail synchronization

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

Queue a read-only sync under rate limiting and an account lease.

cURL 示例

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

GET /api/gmail/messages

列出 Gmail 聚合邮件 / List unified Gmail 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/gmail/messages?limit=30" \
  --header "Authorization: Bearer om_at_..."

GET /api/gmail/accounts/{accountId}/messages/{messageId}

读取 Gmail 正文 / Read a Gmail message

验证账号归属后，通过 BODY.PEEK[] 读取正文，并以受控 STORE 命令同步标记已读。

Verify account ownership, fetch the body with BODY.PEEK[], and synchronize Seen with a controlled STORE command.

cURL 示例

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

GET /api/gmail/accounts/{accountId}/messages/{messageId}/attachments/{partId}

下载 Gmail 附件 / Download a Gmail attachment

验证账号与邮件归属后，按需读取并转发不超过 5 MiB 的附件。

Verify account and message ownership, then fetch and proxy an attachment up to 5 MiB.

cURL 示例

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