Developer reference · 0.x

HTTP API

OmniMail Web、Android、Float 与外部客户端共用的 JSON API。生产环境默认与 Webmail 同源，所有接口位于 /api/*。

Base URL https://mail.example.com/api 体验实例 · mail.zanolab.com ↗

概览认证邮件草稿外部邮箱管理端点

Overview

接口概览

浏览器使用安全 Cookie，桌面客户端使用短期 Access Token 与轮换 Refresh Token。两种方式执行相同的角色、邮箱归属与发信权限检查。

JSON主要数据格式

15 分钟Access Token

30 天Refresh Token

145当前公开端点

0.x 接口当前沿用 /api/*，尚未复制为 /api/v1/*。稳定版前可能新增版本化路径。

Authentication

认证模型

浏览器

HttpOnly + Secure + SameSite=Lax Cookie，由同源 Webmail 自动管理。

桌面客户端

Bearer Access Token 保存在内存，Refresh Token 保存到系统凭据存储。

Authenticated request

GET /api/mailboxes
Authorization: Bearer om_at_...

访问令牌过期或被撤销时返回 401。客户端应只尝试刷新一次；刷新失败后清除本地令牌并重新登录。

Device session

设备令牌

密码与 MFA 验证完成后，桌面端可以签发独立设备会话。令牌明文只返回一次，D1 仅保存 SHA-256 摘要。

POST/api/auth/token

Request

{
  "email": "[email protected]",
  "password": "your-password",
  "deviceName": "OmniMail Desktop / Windows"
}

Success response

{
  "tokenType": "Bearer",
  "accessToken": "om_at_...",
  "expiresIn": 900,
  "refreshToken": "om_rt_...",
  "refreshExpiresIn": 2592000,
  "scopes": ["*"]
}

01签发POST /auth/token

02访问Bearer Access Token

03轮换POST /auth/token/refresh

04撤销POST /auth/token/revoke

Messages

邮件与分页

列表使用不透明游标与“时间 + 唯一 ID”排序。翻页时必须保持 folder、q、mailbox 和 domain 等筛选参数不变。

GET/api/messages?folder=inbox&limit=30

Cursor response

{
  "messages": [],
  "counts": { "unread": 0, "starred": 0 },
  "page": {
    "hasMore": true,
    "nextCursor": "opaque-cursor",
    "limit": 30
  }
}

范围limit 为 1–100；邮件默认 30。
游标客户端不得解析、修改或长期保存。
终点nextCursor = null 或 hasMore = false。
条件同步传回 version，未变化时只返回 unchanged 与版本号。

主动发送

POST/api/messages

Send message

{
  "mailboxAddress": "[email protected]",
  "to": "[email protected]",
  "subject": "Hello",
  "text": "Message body",
  "idempotencyKey": "request_12345678"
}

发件邮箱必须属于当前用户并处于启用状态。相同 idempotencyKey 不会重复投递，也不会重复计入限速。

Drafts & attachments

草稿与附件

GET/api/drafts草稿列表

POST/api/drafts新建草稿

PUT/api/drafts/{draftId}保存草稿

DELETE/api/drafts/{draftId}丢弃草稿

附件通过 multipart/form-data 上传，字段名为 file。单个最多 5 MiB，每封最多 5 个，合计最多 10 MiB。

POST/api/drafts/{draftId}/send

Idempotent send

{ "idempotencyKey": "request_12345678" }

发信服务SendFlare 不支持附件；同域名存在 Resend 配置时自动切换，否则任务明确失败。

External mail workspaces

五类外部邮箱工作区

iCloud、Gmail、Microsoft、QQ 与 Linux DO 邮箱都按当前用户隔离凭据与数据。查询接口不会回传 Cookie、密码、授权码或 OAuth token。

iCloud 隐藏邮箱

13 个端点覆盖账号、加密凭据、隐藏地址预览与管理，以及按需收件箱和正文读取。

Linux DO Mail

10 个端点覆盖连接、验证和轮换凭据，读取与搜索收件箱、发信和查询已发送邮件。

Gmail 聚合收件箱

10 个端点覆盖多账号凭据、受控 IMAP 同步、聚合索引、正文与附件。

Microsoft 邮箱

11 个端点覆盖 OAuth2、受控 IMAP 同步、文件夹、正文、附件与精确已读写入。

QQ 邮箱

11 个端点覆盖授权码认证、INBOX 索引、按需正文与附件，以及受控 SMTP 发信。

隔离连接外部邮箱只连接各自固定的官方端点；凭据使用互不混用的 Worker Secret 加密，正文与附件按需读取。

Administration

管理接口

管理员接口继续执行角色检查。全站邮件与备份恢复演练等高风险能力只对主管理员开放，读取与修改操作会写入审计日志。

全站邮件GET /api/admin/messages筛选、正文、附件、原文与批量操作

部署自检GET /api/admin/deployment-checkcore、security、mail 三组状态

备份演练POST /api/admin/backups/drill只读检查，不导入或覆盖生产对象

版本检查GET /api/admin/version发现新版后引导到 GitHub Fork 同步

操作日志GET /api/admin/audit-logs敏感字段递归移除

发信限速PATCH /api/admin/settings/outbound-rate-limit全局默认与用户覆盖

Errors

常见状态码

401UnauthorizedAccess Token 过期、被撤销或认证缺失。

403Forbidden角色或 Scope 不允许当前操作，或注册功能关闭。

409Conflict启用功能所需的 Worker 配置不完整。

429Rate limited读取 Retry-After 后再重试。

503UnavailableTurnstile 等必需验证服务不可用时失败关闭。

Endpoint index

端点索引

/

50 个常用端点 · 完整 Catalog 共 145 个

GET/api/config

公开运行配置与外部注册状态

POST/api/register

外部注册普通用户

GET/api/session

查询当前 Cookie 或 Bearer 会话

POST/api/auth/token

签发桌面设备令牌

POST/api/auth/token/refresh

轮换 Access 与 Refresh Token

POST/api/auth/token/revoke

撤销设备会话

GET/api/mailboxes

当前用户邮箱列表

POST/api/mailboxes

按用户权限创建邮箱

PATCH/api/mailboxes/{address}

启停邮箱或设置主邮箱

DELETE/api/mailboxes/{address}

隐藏邮箱并启动异步清理

GET/api/messages

邮件列表、筛选与游标分页

POST/api/messages

使用已配置发信服务发送邮件

GET/api/messages/{id}

邮件正文、线程与附件元数据

PATCH/api/messages/{id}

更新已读、星标与文件夹状态

PATCH/api/messages/bulk

最多 50 封邮件的批量操作

DELETE/api/messages/{id}

永久删除垃圾箱邮件

GET/api/messages/{id}/raw

下载原始 .eml

POST/api/messages/{id}/reply

在线程内回复，支持附件

GET/api/drafts

当前用户草稿列表

POST/api/drafts

新建服务端草稿

PUT/api/drafts/{id}

保存指定草稿

POST/api/drafts/{id}/attachments

上传草稿附件

POST/api/drafts/{id}/send

幂等发送草稿及附件

GET/api/icloud/accounts

列出当前用户连接的 iCloud 账号

POST/api/icloud/accounts

验证并连接 iCloud 账号

GET/api/icloud/aliases

列出 Hide My Email 地址

POST/api/icloud/aliases

保留候选隐藏邮箱地址

GET/api/icloud/inbox

按需读取或搜索 iCloud 来信

GET/api/gmail/accounts

列出当前用户连接的 Gmail 账号

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

请求受限的异步 Gmail 同步

GET/api/gmail/messages

搜索 Gmail 元数据索引并分页

GET/api/microsoft/accounts

列出脱敏 Microsoft 账号与同步状态

POST/api/microsoft/accounts/import

验证并批量导入 OAuth2 账号

GET/api/microsoft/messages

按账号和文件夹搜索 Microsoft 邮件

GET/api/qq-mail/accounts

列出当前用户连接的 QQ 邮箱账号

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

通过 QQ SMTP 发送或回复邮件

GET/api/qq-mail/messages

搜索 QQ 邮箱元数据索引并分页

GET/api/linux-do-mail/account

查询当前 Linux DO Mail 连接

POST/api/linux-do-mail/account

验证并连接 Linux DO Mail

POST/api/linux-do-mail/messages

通过官方 SMTP 发送邮件

GET/api/linux-do-mail/inbox

读取或搜索最近来信

GET/api/linux-do-mail/sent

读取已发送邮件记录

GET/api/admin/statistics

管理员邮件统计

GET/api/admin/messages

主管理员查询全站邮件

GET/api/admin/audit-logs

操作日志、筛选与分页

GET/api/admin/deployment-check

资源与服务配置自检

GET/api/admin/version

当前版本与 Release 状态

GET/api/admin/users

管理员用户列表

GET/api/admin/backups/objects

分页浏览备份对象

POST/api/admin/backups/drill

只读备份结构演练

Source of truth

完整 API 文档

145 个真实端点已按 13 个业务分类生成 Markdown 参考；架构、安全、限速与数据生命周期仍由 docs/API.md 说明。

打开完整端点目录