邮件服务

模块类型：service ｜基础路径：/api/v2/mail ｜鉴权：设备 APIKey

应用须在后台启用 mail 服务（否则 403）。

设备 App 内的邮件功能。邮箱凭证（地址 / IMAP·SMTP 主机与授权码）由客户端每次请求携带，服务端不存储。

通用约定

均为 POST、apikey、noQuota。

路径	额外请求体字段	说明 / result
`/overview/:appname`	—	邮箱概览（文件夹 / 未读等统计）
`/list/:appname`	`start?`、`end?`、`folder?`、`textOverflow?`、`UTCoffset?`	邮件摘要列表（分页）
`/starred/:appname`	同 list	星标邮件列表
`/info/:appname`	`emailId`、`folder`、`Type?='json'`、`textOverflow?`、`UTCoffset?`、`markRead?=true`	单封邮件完整内容（正文 / 附件列表 / 时间）；`markRead:false` 只预览不置已读
`/folders/:appname`	—	邮箱文件夹列表
`/search/:appname`	`keyword`、`start?`、`end?`、`folder?`、`textOverflow?`、`UTCoffset?`	关键词搜索结果

分页用 start / end（而非页码）；folder 默认为 INBOX；textOverflow 控制正文截断长度。

均为 POST、apikey、noQuota。

路径	请求体字段	说明
`/flag/:appname`	`emailId`、`action`、`folder?`	标记：`seen` / `unseen` / `flagged` / `unflagged` 等
`/delete/:appname`	`emailId`、`folder?`	删除邮件
`/move/:appname`	`emailId`、`targetFolder`、`folder?`	移动到文件夹
`/batch-flag/:appname`	`emailIds[]`、`action`、`folder?`	批量标记
`/batch-move/:appname`	`emailIds[]`、`targetFolder`、`folder?`	批量移动
`/batch-delete/:appname`	`emailIds[]`、`folder?`	批量删除

均为 POST、apikey、noQuota。

均为 POST、apikey、noQuota。

路径	请求体字段	说明
`/draft-save/:appname`	`sendto`、`title`、`text` 等（IMAP 凭证同公共字段）	保存草稿
`/draft-delete/:appname`	`emailId`	删除草稿

请求体：

成功： { "status": 200, "message": "邮件发送成功" }。HTML 正文会经白名单清洗。

项目	内容
API	`POST /api/v2/mail/verify/:appname`
鉴权	设备 APIKey（noQuota）
说明	测试 IMAP / SMTP 连通性

请求体含 Key、email，及可选的 imap* / smtp* 配置。

返回：

{
  "status": 200,
  "result": {
    "imap": { "success": true, "message": "连接成功" },
    "smtp": { "success": true, "message": "连接成功" }
  }
}

附件返回二进制流（非统一信封），提供两种方式：

方式	API	鉴权	说明
POST	`/api/v2/mail/attachment/:appname`	设备 APIKey（noQuota）	请求体 `emailId`、`attachmentIndex`、`folder?` + 公共 IMAP 字段，返回二进制流
GET	`/api/v2/mail/attachment/:appname/:emailId/:attachmentIndex?token=<令牌>`	公开（凭令牌）	供前端 `<img src>` / `<a href>` 直接引用

GET 附件 URL 的 token 由 /info 返回的附件 URL 提供（AES-256-GCM 签名，绑定应用 / 邮箱 / 邮件 / 序号），过期或不匹配返回 401 / 403。这样无需在 URL 暴露 IMAP 凭证。