API 参考

所有接口都挂在同一个 Worker 上,与 SPA 共享域名。鉴权基于 Cookie 会话, Cookie 由 /api/auth/callback 在 Prism OAuth 回跳后写入,并在每次请求时被校验。 管理员接口要求 role ∈ { owner, co-owner }。

鉴权

方法	路径	说明
GET	/api/auth/config	SPA 用的公开 OAuth 配置
GET	/api/auth/me	当前用户,未登录返回 { user: null }
POST	/api/auth/callback	用授权码换取会话
POST	/api/auth/logout	退出登录

初始化

方法	路径	说明
GET	/api/init/status	{ configured, configStaged }
GET	/api/init/branding	站点名称、Logo
GET	/api/init/config	完整 AppConfig(初始化前公开,完成后仅 owner 可读)
PUT	/api/init/config	同上,Patch 操作
POST	/api/init/setup	阶段 1:持久化配置 + 建表,等待 owner 登录

POST /api/init/setup 在 “已配置” 或 “已暂存配置” 时拒绝执行—— 此时只能由 owner 登录来推进流程。

邮箱

方法	路径	说明
GET	/api/folders	文件夹列表与计数
POST	/api/folders	新建自定义文件夹
PATCH	/api/folders/:id	重命名文件夹
DELETE	/api/folders/:id	删除文件夹,邮件回到 inbox
GET	/api/messages?folder=&cursor=&q=	分页邮件列表
GET	/api/messages/:id	邮件正文与附件
PATCH	/api/messages/:id	标记已读/星标/移动文件夹
DELETE	/api/messages/:id	软删(回收站)或硬删
POST	/api/messages/bulk	批量操作 { ids[] }(单次最多 500 个)
POST	/api/messages/trash/empty	清空当前用户回收站
GET	/api/threads/:threadId	同一会话的全部邮件
GET	/api/messages/:id/attachments/:attId	下载附件
GET	/api/messages/:id/raw	下载原始 .eml

发送与草稿

方法	路径	说明
POST	/api/send	发信。From 必须是已分配给本人的地址
POST	/api/drafts	草稿 Upsert(对应一行 folder='drafts' 邮件)

成员侧地址

方法	路径	说明
GET	/api/addresses	当前用户被分配的地址

成员 无法 自行新增 / 删除地址。

管理(owner / co-owner 专属)

方法	路径	说明
GET	/api/admin/members	Lumen 已识别的全部成员及其存储限额
GET	/api/admin/addresses	全部地址分配关系
POST	/api/admin/addresses	分配 { userId, address, displayName? }
PUT	/api/admin/addresses/:id	修改显示名
DELETE	/api/admin/addresses/:id	移除分配
PUT	/api/admin/addresses/:id/primary	设为该用户的主地址
PUT	/api/admin/members/:userId/limits	设置或清除单用户 maxStorageBytes 与 maxMessageBytes(null = 继承,0 = 不限)
GET	/api/admin/stats/storage	全站合计:已用字节、邮件数

用户首次完成 Prism 登录后才会被 Lumen “识别”。

实时

方法	路径	说明
GET	/api/ws	WebSocket。向当前用户推送 LumenEvent。

LumenEvent:

type LumenEvent =
  | { kind: "incoming"; folder: string; messageId: string }
  | { kind: "changed";  folder: string; messageId: string }
  | { kind: "deleted";  folder: string; messageId: string }
  | { kind: "folders" };

图片代理

方法	路径	说明
GET	/api/proxy/image?url=…	服务端图片代理(带 SSRF 防护)

详见 存储与限额。

联系人 / 设置

方法	路径	说明
GET	/api/contacts?q=	按使用频次排序的联系人
GET	/api/settings	用户设置 + 站点默认
PUT	/api/settings	更新用户设置