Developer reference · 0.x

HTTP API

OmniMail Web 与桌面客户端共用的 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

1–100分页 limit 范围

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": "user@example.com",
  "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": "owner@example.com",
  "to": "friend@example.net",
  "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 配置时自动切换，否则任务明确失败。

Administration

管理接口

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

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

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

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

版本更新POST /api/admin/version/update按 Release Tag 提交 SHA 触发构建

操作日志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

端点索引

/

32 个常用端点

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/admin/statistics

管理员邮件统计

GET/api/admin/messages

主管理员查询全站邮件

GET/api/admin/audit-logs

操作日志、筛选与分页

GET/api/admin/deployment-check

资源与服务配置自检

GET/api/admin/version

当前版本与 Release 状态

POST/api/admin/version/update

按最新 Release Tag 启动构建

GET/api/admin/users

管理员用户列表

GET/api/admin/backups/objects

分页浏览备份对象

POST/api/admin/backups/drill

只读备份结构演练

Source of truth

完整 API 文档

邀请、浏览器扩展 PKCE、注册保护、备份、更新与管理员设置的全部安全约束，请阅读仓库原始文档。

打开 docs/API.md