770 lines
23 KiB
Markdown
770 lines
23 KiB
Markdown
# Smail 后端接口说明文档
|
||
|
||
> 本文档用于说明当前 Smail 后端 HTTP API 的实际调用方式，并对照原版 PMail《后端接口文档》核对接口是否仍然存在。
|
||
>
|
||
> 核对基准：当前代码分支 `main`，提交 `6ec4628`，核对日期：2026-08-27。
|
||
|
||
## 1. 文档范围和结论
|
||
|
||
原版 PMail 文档包含 9 个基础接口。当前 Smail 仍然保留其中 8 个接口的功能入口，但有以下路径或调用方式变化：
|
||
|
||
| 编号 | 原版接口 | 当前实际接口 | 当前状态 | 主要差异 |
|
||
|---|---|---|---|---|
|
||
| 1 | `/api/ping` | `/api/ping` | 存在 | 当前返回统一 JSON，不再是纯文本 `pong` |
|
||
| 2 | `/api/login` | `/api/login` | 存在 | 只接受 `POST`；使用会话 Cookie 和 CSRF Cookie，不使用原版文档所述的 `token` 请求头 |
|
||
| 3 | `/api/group` | `/api/group` | 部分兼容 | 当前只接受 `GET`，原版写的 `POST` 不再可用；另有 `/api/group/list` |
|
||
| 4 | `/api/email/list` | `/api/email/list` | 存在 | 只接受 `POST`，分页参数增加范围限制 |
|
||
| 5 | `/api/detail` | `/api/email/detail` | 路径已变更 | 原路径不存在，必须使用 `/api/email/detail` |
|
||
| 6 | `/api/email/send` | `/api/email/send` | 存在 | 只接受 `POST`，增加发件人校验、附件和收件人数限制 |
|
||
| 7 | `/api/settings/modify_password` | `/api/settings/modify_password` | 存在 | 当前需要同时提交 `current_password` 和 `password` |
|
||
| 8 | `/attachments/` | `/attachments/{邮件ID}/{内容标识}` | 存在 | 当前只接受 `GET`，用于内联展示附件内容 |
|
||
| 9 | `/attachments/download/` | `/attachments/download/{邮件ID}/{附件序号}` | 存在 | 当前只接受 `GET`，最后一段是附件序号，不是附件数据库 ID |
|
||
|
||
当前路由注册以 `server/listen/http_server/http_server.go` 为准，接口处理逻辑以 `server/controllers` 和 `server/controllers/email` 为准。
|
||
|
||
## 2. 通用调用约定
|
||
|
||
### 2.1 基础地址
|
||
|
||
以下示例使用：
|
||
|
||
```text
|
||
https://mail.example.com
|
||
```
|
||
|
||
请替换为实际的 Smail Web 地址。开发环境也可以使用：
|
||
|
||
```text
|
||
http://127.0.0.1:80
|
||
```
|
||
|
||
生产环境应优先使用 HTTPS。
|
||
|
||
### 2.2 通用响应格式
|
||
|
||
除附件内容下载接口外，JSON 接口统一返回以下结构：
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `errorNo` | number | `0` 表示成功；非 `0` 表示失败。常见值：`100` 参数错误、`403` 未登录、`405` 无权限、`500` 服务端错误 |
|
||
| `errorMsg` | string | 错误说明。生产环境不应依赖错误文本判断业务分支，应优先判断 `errorNo` |
|
||
| `data` | any | 成功数据或错误附加数据 |
|
||
|
||
请求方法不正确时，路由层返回 HTTP `405 Method Not Allowed`，并通过 `Allow` 响应头提示允许的方法；此时不一定返回上面的 JSON 结构。
|
||
|
||
### 2.3 登录态和 CSRF
|
||
|
||
除探活、登录和公开的密码恢复流程外，邮件、分组、密码修改等接口都需要登录态。
|
||
|
||
登录成功后，服务端会设置：
|
||
|
||
1. 会话 Cookie，用于识别登录用户；
|
||
2. `smail_csrf` Cookie，用于保存 CSRF Token；
|
||
3. 后续状态修改请求需要在 `X-CSRF-Token` 请求头中提交与 `smail_csrf` Cookie 相同的值。
|
||
|
||
对于携带登录会话 Cookie 的状态修改请求，还需要使用同源的 `Origin`；跨站请求或 CSRF Token 不匹配时会被拒绝。
|
||
|
||
建议使用浏览器或 HTTP 客户端的 Cookie Jar 保存登录后的 Cookie，不要手工复制会话 Cookie 到代码或日志中。
|
||
|
||
### 2.4 请求头
|
||
|
||
JSON 请求通常应携带：
|
||
|
||
```http
|
||
Content-Type: application/json
|
||
```
|
||
|
||
需要登录的状态修改请求示例：
|
||
|
||
```http
|
||
Cookie: 会话Cookie; smail_csrf=CSRF_TOKEN
|
||
X-CSRF-Token: CSRF_TOKEN
|
||
Origin: https://mail.example.com
|
||
```
|
||
|
||
`Lang` 请求头可以指定返回语言，例如：
|
||
|
||
```http
|
||
Lang: zh-CN
|
||
```
|
||
|
||
未指定时由服务端使用默认语言处理。
|
||
|
||
### 2.5 通用错误处理
|
||
|
||
调用方建议按以下顺序处理：
|
||
|
||
1. 先检查 HTTP 状态码；
|
||
2. 对 JSON 响应解析 `errorNo`、`errorMsg` 和 `data`；
|
||
3. 收到 `403` 或业务错误码表示登录失效时，重新登录；
|
||
4. 收到 `405` 时检查请求方法，不要重试相同方法；
|
||
5. 不要把密码、会话 Cookie、CSRF Token、完整邮箱地址写入日志。
|
||
|
||
## 3. 原版基础接口对照和调用说明
|
||
|
||
## 3.1 服务探活
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/api/ping` |
|
||
| 当前路径 | `/api/ping` |
|
||
| 当前方法 | `GET`、`POST` 均可到达处理器；建议使用 `GET` |
|
||
| 是否需要登录 | 否 |
|
||
| 请求体 | 无 |
|
||
| 返回类型 | JSON |
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X GET "https://mail.example.com/api/ping"
|
||
```
|
||
|
||
也可以使用：
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/ping"
|
||
```
|
||
|
||
### 返回示例
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": "pong"
|
||
}
|
||
```
|
||
|
||
### 与原版差异
|
||
|
||
原版文档把返回格式写成 `text`，示例为纯文本 `pong`。当前代码通过统一响应封装返回 JSON，实际数据位于 `data` 字段中。
|
||
|
||
## 3.2 用户登录
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/api/login` |
|
||
| 当前路径 | `/api/login` |
|
||
| 方法 | `POST` |
|
||
| 是否需要登录 | 否 |
|
||
| 请求格式 | `application/json` |
|
||
| 返回类型 | JSON |
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---:|---|
|
||
| `identifier` | string | 否 | 登录标识。当前优先使用该字段，可填写账号或完整邮箱 |
|
||
| `account` | string | 否 | 兼容原版字段。当 `identifier` 为空时使用该字段 |
|
||
| `password` | string | 是 | 登录密码 |
|
||
|
||
`identifier` 和 `account` 至少提供一个。为了兼容原版客户端，可以继续提交 `account`；新客户端建议使用 `identifier`。
|
||
|
||
### 调用示例
|
||
|
||
兼容原版字段：
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/login" \
|
||
-H "Content-Type: application/json" \
|
||
-c cookies.txt \
|
||
-d '{
|
||
"account": "admin",
|
||
"password": "your-password"
|
||
}'
|
||
```
|
||
|
||
使用新的登录标识字段：
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/login" \
|
||
-H "Content-Type: application/json" \
|
||
-c cookies.txt \
|
||
-d '{
|
||
"identifier": "admin@example.com",
|
||
"password": "your-password"
|
||
}'
|
||
```
|
||
|
||
### 成功返回示例
|
||
|
||
普通登录直接完成时，返回：
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": {
|
||
"account": "admin",
|
||
"name": "管理员",
|
||
"role": "super_admin",
|
||
"is_admin": 1,
|
||
"domains": [
|
||
"example.com"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
登录成功时，服务端同时通过 `Set-Cookie` 设置会话 Cookie 和 CSRF Cookie。客户端必须保存这两个 Cookie，后续接口才能继续调用。
|
||
|
||
### 二次验证情况
|
||
|
||
如果当前账号启用了登录二次验证，密码正确后可能返回一个待完成的验证数据，而不是直接建立完整登录态。客户端应根据返回的 `data` 调用登录验证接口：
|
||
|
||
```text
|
||
POST /api/security/login/verify
|
||
```
|
||
|
||
该流程不属于原版 PMail 基础接口，详细接口以本文第 4 节的当前安全接口表和前端调用为准。
|
||
|
||
### 失败返回示例
|
||
|
||
```json
|
||
{
|
||
"errorNo": 100,
|
||
"errorMsg": "参数错误",
|
||
"data": ""
|
||
}
|
||
```
|
||
|
||
为了防止账号枚举，登录失败、账号不存在、密码错误和登录限流通常使用相同的业务错误响应，调用方不要根据错误文本判断账号是否存在。
|
||
|
||
### 与原版差异
|
||
|
||
原版文档提到可以通过请求头 `token` 进行验签。当前代码路由和认证逻辑未发现该兼容方式，当前登录态以服务端会话 Cookie 为准，不应使用 `token` 请求头替代登录。
|
||
|
||
## 3.3 获取邮件分组树
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/api/group` |
|
||
| 当前路径 | `/api/group` |
|
||
| 方法 | `GET` |
|
||
| 原版方法 | `POST/GET` |
|
||
| 是否需要登录 | 是 |
|
||
| 请求体 | 无 |
|
||
| 返回类型 | JSON |
|
||
|
||
当前 `/api/group` 只注册了 `GET`。使用原版文档中的 `POST` 调用会返回 HTTP `405`。
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X GET "https://mail.example.com/api/group" \
|
||
-b cookies.txt
|
||
```
|
||
|
||
如果是浏览器外的状态修改场景，读取接口不需要提交 CSRF Token；但必须携带有效会话 Cookie。
|
||
|
||
### 返回示例
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": [
|
||
{
|
||
"label": "收件箱",
|
||
"tag": "{\"type\":0,\"status\":-1,\"group_id\":0}"
|
||
},
|
||
{
|
||
"label": "发件箱",
|
||
"tag": "{\"type\":1,\"status\":-1}"
|
||
},
|
||
{
|
||
"label": "草稿箱",
|
||
"tag": "{\"type\":0,\"status\":4}"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 当前相关分组接口
|
||
|
||
| 方法 | 路径 | 说明 | 请求体 |
|
||
|---|---|---|---|
|
||
| `GET` | `/api/group` | 获取前端使用的分组树 | 无 |
|
||
| `GET` | `/api/group/list` | 获取默认分组和用户自定义分组列表 | 无 |
|
||
| `POST` | `/api/group/add` | 创建自定义分组 | `{"name":"项目邮件","parent_id":0}` |
|
||
| `POST` | `/api/group/del` | 删除自定义分组 | `{"id":1}` |
|
||
|
||
`POST /api/group/add` 和 `POST /api/group/del` 属于状态修改接口，需要登录态和 CSRF Token。
|
||
|
||
## 3.4 获取邮件列表
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 路径 | `/api/email/list` |
|
||
| 方法 | `POST` |
|
||
| 是否需要登录 | 是 |
|
||
| 请求格式 | `application/json` |
|
||
| 返回类型 | JSON |
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
|---|---|---:|---:|---|
|
||
| `keyword` | string | 否 | 空字符串 | 邮件搜索关键词，最多 512 字节 |
|
||
| `tag` | string | 否 | 全部邮件 | JSON 字符串形式的筛选条件 |
|
||
| `current_page` | integer | 否 | `1` | 当前页，从 `1` 开始，最大 `10000` |
|
||
| `page_size` | integer | 否 | `15` | 每页数量，最大 `100` |
|
||
|
||
`tag` 是一个字符串字段，内容需要再次编码为 JSON，例如：
|
||
|
||
```json
|
||
"{\"type\":0,\"status\":-1,\"group_id\":0}"
|
||
```
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/email/list" \
|
||
-H "Content-Type: application/json" \
|
||
-b cookies.txt \
|
||
-H "X-CSRF-Token: CSRF_TOKEN" \
|
||
-H "Origin: https://mail.example.com" \
|
||
-d '{
|
||
"keyword": "验证码",
|
||
"tag": "{\"type\":0,\"status\":-1,\"group_id\":0}",
|
||
"current_page": 1,
|
||
"page_size": 15
|
||
}'
|
||
```
|
||
|
||
### 返回示例
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": {
|
||
"current_page": 1,
|
||
"total_page": 1,
|
||
"list": [
|
||
{
|
||
"id": 1,
|
||
"title": "邮件标题",
|
||
"desc": "邮件正文摘要",
|
||
"datetime": "2026-08-27 08:44:00",
|
||
"is_read": false,
|
||
"sender": {
|
||
"Name": "发件人",
|
||
"EmailAddress": "sender@example.com"
|
||
},
|
||
"to": [
|
||
{
|
||
"Name": "收件人",
|
||
"EmailAddress": "admin@example.com"
|
||
}
|
||
],
|
||
"dangerous": false,
|
||
"error": ""
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 分页说明
|
||
|
||
- 不提交分页参数时使用 `current_page=1`、`page_size=15`；
|
||
- `current_page` 小于 `1` 或大于 `10000` 会被拒绝；
|
||
- `page_size` 小于 `1` 或大于 `100` 会被拒绝；
|
||
- `keyword` 超过 512 字节会被拒绝；
|
||
- `total_page` 在没有邮件时为 `0`。
|
||
|
||
## 3.5 获取邮件详情
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/api/detail` |
|
||
| 当前路径 | `/api/email/detail` |
|
||
| 方法 | `POST` |
|
||
| 是否需要登录 | 是 |
|
||
| 请求格式 | `application/json` |
|
||
| 返回类型 | JSON |
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---:|---|
|
||
| `id` | integer | 是 | 邮件 ID，必须大于 `0` |
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/email/detail" \
|
||
-H "Content-Type: application/json" \
|
||
-b cookies.txt \
|
||
-H "X-CSRF-Token: CSRF_TOKEN" \
|
||
-H "Origin: https://mail.example.com" \
|
||
-d '{
|
||
"id": 1
|
||
}'
|
||
```
|
||
|
||
### 返回示例
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": {
|
||
"id": 1,
|
||
"type": 0,
|
||
"subject": "邮件标题",
|
||
"reply_to": "",
|
||
"from_name": "发件人",
|
||
"from_address": "sender@example.com",
|
||
"to": "[{\"Name\":\"收件人\",\"EmailAddress\":\"admin@example.com\"}]",
|
||
"bcc": "[]",
|
||
"cc": "[]",
|
||
"sender": "{\"Name\":\"发件人\",\"EmailAddress\":\"sender@example.com\"}",
|
||
"spf_check": 1,
|
||
"dkim_check": 1,
|
||
"status": 1,
|
||
"send_time": "2026-08-27 08:44:00",
|
||
"send_date": "2026-08-27 08:44:00",
|
||
"update_time": "2026-08-27 08:44:00",
|
||
"create_time": "2026-08-27 08:44:00",
|
||
"text": "纯文本正文",
|
||
"html": "<div>HTML正文</div>",
|
||
"error": "",
|
||
"attachments": [
|
||
{
|
||
"Filename": "report.pdf",
|
||
"ContentType": "application/pdf",
|
||
"Index": 0
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 与原版差异
|
||
|
||
原版文档使用 `/api/detail`。当前该路径没有注册，必须改为 `/api/email/detail`。邮件详情请求会标记邮件为已读，因此调用该接口不是纯读取操作；使用 `POST` 也符合当前路由约束。
|
||
|
||
## 3.6 发送邮件
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 路径 | `/api/email/send` |
|
||
| 方法 | `POST` |
|
||
| 是否需要登录 | 是 |
|
||
| 请求格式 | `application/json` |
|
||
| 返回类型 | JSON |
|
||
| 请求体上限 | 40 MiB |
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---:|---|
|
||
| `reply_to` | array | 否 | 回复地址列表，每项包含 `name`、`email` |
|
||
| `from` | object | 否 | 发件人，包含 `name`、`email`；邮箱为空时使用当前账号地址 |
|
||
| `to` | array | 是 | 收件人列表，每项包含 `name`、`email` |
|
||
| `bcc` | array | 否 | 密送列表 |
|
||
| `cc` | array | 否 | 抄送列表 |
|
||
| `subject` | string | 是 | 邮件标题 |
|
||
| `text` | string | 否 | 纯文本正文 |
|
||
| `html` | string | 否 | HTML 正文 |
|
||
| `sender` | object | 否 | SMTP Envelope Sender；为空时使用 `from` |
|
||
| `read_receipt` | array | 否 | 已读回执地址列表 |
|
||
| `attrs` | array | 否 | 附件列表，每项包含 `name`、`data` |
|
||
|
||
`attrs[].data` 必须是 Data URL 格式的 Base64 数据，例如：
|
||
|
||
```text
|
||
data:application/pdf;base64,BASE64_DATA
|
||
```
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/email/send" \
|
||
-H "Content-Type: application/json" \
|
||
-b cookies.txt \
|
||
-H "X-CSRF-Token: CSRF_TOKEN" \
|
||
-H "Origin: https://mail.example.com" \
|
||
-d '{
|
||
"from": {
|
||
"name": "管理员",
|
||
"email": "admin@example.com"
|
||
},
|
||
"to": [
|
||
{
|
||
"name": "收件人",
|
||
"email": "user@example.com"
|
||
}
|
||
],
|
||
"cc": [],
|
||
"bcc": [],
|
||
"subject": "测试邮件",
|
||
"text": "这是纯文本正文。",
|
||
"html": "<p>这是 HTML 正文。</p>",
|
||
"attrs": []
|
||
}'
|
||
```
|
||
|
||
### 成功返回
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": "操作成功"
|
||
}
|
||
```
|
||
|
||
接口返回成功表示邮件已经通过参数校验并创建发送任务。实际投递结果可能在异步处理后才确定，失败信息会写入邮件状态，调用方应通过邮件列表或详情接口检查最终状态。
|
||
|
||
### 当前限制
|
||
|
||
- `to` 至少包含一个收件人；
|
||
- `to`、`cc`、`bcc`、`reply_to` 合计最多 `100` 个地址；
|
||
- 附件最多 `20` 个；
|
||
- 单个附件最大 `10 MiB`；
|
||
- 附件总大小最大 `25 MiB`；
|
||
- 邮件正文最大约 `8 MiB`；
|
||
- `subject` 必填；
|
||
- 普通用户不能伪造未授权的内部发件人地址；
|
||
- 附件文件名会进行路径和控制字符清理。
|
||
|
||
## 3.7 修改当前账号密码
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/api/settings/modify_password` |
|
||
| 当前路径 | `/api/settings/modify_password` |
|
||
| 方法 | `POST` |
|
||
| 是否需要登录 | 是 |
|
||
| 请求格式 | `application/json` |
|
||
| 返回类型 | JSON |
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|---|---|---:|---|
|
||
| `current_password` | string | 是 | 当前密码 |
|
||
| `password` | string | 是 | 新密码，长度为 8 到 256 字节 |
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X POST "https://mail.example.com/api/settings/modify_password" \
|
||
-H "Content-Type: application/json" \
|
||
-b cookies.txt \
|
||
-H "X-CSRF-Token: CSRF_TOKEN" \
|
||
-H "Origin: https://mail.example.com" \
|
||
-d '{
|
||
"current_password": "old-password",
|
||
"password": "new-password"
|
||
}'
|
||
```
|
||
|
||
### 成功返回
|
||
|
||
```json
|
||
{
|
||
"errorNo": 0,
|
||
"errorMsg": "",
|
||
"data": "操作成功"
|
||
}
|
||
```
|
||
|
||
修改成功后，当前账号的安全凭据和登录会话会按服务端策略刷新或撤销。调用方如果收到会话失效，应重新登录并重新获取 CSRF Token。
|
||
|
||
### 与原版差异
|
||
|
||
原版示例中的 `passowrd` 是拼写错误，当前代码使用正确字段 `password`。当前接口还要求提供 `current_password`，不能只提交新密码。
|
||
|
||
## 3.8 内联获取附件内容
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/attachments/` |
|
||
| 当前路径 | `/attachments/{邮件ID}/{内容标识}` |
|
||
| 方法 | `GET` |
|
||
| 原版方法 | 文档写成 `POST`，但请求示例使用 `GET` |
|
||
| 是否需要登录 | 是 |
|
||
| 返回类型 | 附件原始内容 |
|
||
|
||
其中：
|
||
|
||
- `{邮件ID}` 是邮件 ID；
|
||
- `{内容标识}` 是邮件详情中附件的内容标识，通常对应内联资源的 Content-ID；
|
||
- 当前处理器会按路径读取这两个值，并检查当前用户是否有权访问该邮件附件。
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X GET "https://mail.example.com/attachments/1/image001.png" \
|
||
-b cookies.txt \
|
||
-o image001.png
|
||
```
|
||
|
||
### 返回说明
|
||
|
||
成功时返回附件原始字节，并设置对应的 `Content-Type`，例如：
|
||
|
||
```http
|
||
Content-Type: image/png
|
||
```
|
||
|
||
失败时返回统一 JSON 错误响应。常见原因包括路径格式错误、附件不存在、附件不可用或当前用户无权访问。
|
||
|
||
## 3.9 下载附件
|
||
|
||
### 接口信息
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 原版路径 | `/attachments/download/` |
|
||
| 当前路径 | `/attachments/download/{邮件ID}/{附件序号}` |
|
||
| 方法 | `GET` |
|
||
| 是否需要登录 | 是 |
|
||
| 返回类型 | 文件流 |
|
||
|
||
其中 `{附件序号}` 是邮件详情 `attachments` 数组中的 `Index`，当前从 `0` 开始，不是附件数据库 ID。
|
||
|
||
### 调用示例
|
||
|
||
```bash
|
||
curl -X GET "https://mail.example.com/attachments/download/1/0" \
|
||
-b cookies.txt \
|
||
-o report.pdf
|
||
```
|
||
|
||
### 返回响应头
|
||
|
||
成功时服务端返回：
|
||
|
||
```http
|
||
Content-Type: application/octet-stream
|
||
X-Content-Type-Options: nosniff
|
||
Content-Disposition: attachment; filename="attachment"; filename*=UTF-8''report.pdf
|
||
```
|
||
|
||
服务端会清理文件名中的路径分隔符、换行符和控制字符，避免下载文件名被用于路径穿越或响应头注入。
|
||
|
||
## 4. 当前新增安全和账户接口
|
||
|
||
这些接口不在原版 PMail 的 9 个基础接口中，但已经注册在当前 Smail 路由中。它们属于当前前端登录、安全设置和密码恢复流程的一部分。
|
||
|
||
### 4.1 登录和恢复流程
|
||
|
||
| 方法 | 路径 | 是否公开 | 说明 |
|
||
|---|---|---:|---|
|
||
| `POST` | `/api/security/verification/request` | 否 | 请求验证信息 |
|
||
| `POST` | `/api/security/verification/verify` | 否 | 校验验证信息 |
|
||
| `POST` | `/api/security/login/verify` | 是 | 完成登录二次验证 |
|
||
| `POST` | `/api/security/recovery/begin` | 是 | 开始密码恢复流程 |
|
||
| `POST` | `/api/security/recovery/verify` | 是 | 校验密码恢复凭据 |
|
||
| `POST` | `/api/security/recovery/complete` | 是 | 完成密码恢复 |
|
||
| `POST` | `/api/security/recovery/webauthn/begin` | 是 | 开始 WebAuthn 恢复验证 |
|
||
| `POST` | `/api/security/recovery/webauthn/verify` | 是 | 完成 WebAuthn 恢复验证 |
|
||
| `POST` | `/api/logout` | 否 | 退出当前会话 |
|
||
|
||
### 4.2 WebAuthn 和恢复码
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `POST` | `/api/security/webauthn/registration/begin` | 开始注册安全密钥 |
|
||
| `POST` | `/api/security/webauthn/registration/finish` | 完成注册安全密钥 |
|
||
| `GET` | `/api/security/webauthn/credentials` | 查询当前账号安全密钥 |
|
||
| `POST` | `/api/security/webauthn/credentials/rename` | 重命名安全密钥 |
|
||
| `POST` | `/api/security/webauthn/credentials/revoke` | 撤销安全密钥 |
|
||
| `POST` | `/api/security/webauthn/login/begin` | 开始登录安全密钥验证 |
|
||
| `POST` | `/api/security/webauthn/login/finish` | 完成登录安全密钥验证 |
|
||
| `GET` | `/api/security/credentials/recovery-codes` | 查询恢复码状态，不返回历史恢复码原文 |
|
||
| `POST` | `/api/security/credentials/recovery-codes/generate` | 生成新的恢复码 |
|
||
| `POST` | `/api/security/credentials/recovery-codes/revoke` | 撤销恢复码 |
|
||
| 未限制 | `/api/security/credentials/question` | 密保问题相关流程入口，实际方法由处理器判断 |
|
||
|
||
### 4.3 外部安全邮箱
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `GET` | `/api/security/external-email/list` | 获取当前账号外部安全邮箱状态 |
|
||
| `POST` | `/api/security/external-email/bind` | 绑定外部安全邮箱 |
|
||
| `POST` | `/api/security/external-email/verify` | 验证外部安全邮箱 |
|
||
| `POST` | `/api/security/external-email/disable` | 禁用外部安全邮箱 |
|
||
|
||
以上安全接口的请求参数和恢复状态机依赖当前安全设计，不应按照原版 PMail 的 `token` 模式调用。
|
||
|
||
## 5. 当前邮件和账户管理接口补充
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| `POST` | `/api/email/del` | 删除邮件 |
|
||
| `POST` | `/api/email/read` | 标记邮件已读 |
|
||
| `POST` | `/api/email/move` | 移动邮件到分组 |
|
||
| `POST` | `/api/rule/get` | 获取邮件规则 |
|
||
| `POST` | `/api/rule/add` | 新增邮件规则 |
|
||
| `POST` | `/api/rule/update` | 更新邮件规则 |
|
||
| `POST` | `/api/rule/del` | 删除邮件规则 |
|
||
| `POST` | `/api/user/create` | 创建用户，权限由当前角色控制 |
|
||
| `POST` | `/api/user/edit` | 编辑用户 |
|
||
| `POST` | `/api/user/info` | 获取用户信息 |
|
||
| `POST` | `/api/user/list` | 获取用户列表 |
|
||
| `GET` | `/api/plugin/list` | 获取插件列表 |
|
||
| `GET`、`POST` | `/api/plugin/settings/{插件名}/{操作}` | 读取或保存插件设置 |
|
||
|
||
配置管理接口使用 `/api/v1/config/` 和 `/api/v1/audits/config` 路径，属于新的配置系统，不属于原版 PMail 基础接口；调用时需要按当前配置授权、审计和 CSRF 规则处理。
|
||
|
||
## 6. 原版接口迁移清单
|
||
|
||
使用原版 PMail 客户端迁移到当前 Smail 时，至少需要修改以下内容：
|
||
|
||
| 原版调用 | 当前调用 |
|
||
|---|---|
|
||
| `POST /api/detail` | `POST /api/email/detail` |
|
||
| `POST /api/group` | `GET /api/group` |
|
||
| `POST /attachments/{邮件ID}/{附件标识}` | `GET /attachments/{邮件ID}/{附件标识}` |
|
||
| 仅提交 `password` 修改密码 | 同时提交 `current_password` 和 `password` |
|
||
| 使用 `token` 请求头认证 | 保存登录会话 Cookie，并在状态修改请求中提交 `X-CSRF-Token` |
|
||
| 将 `/api/ping` 当作纯文本读取 | 解析 JSON，并读取 `data` 中的 `pong` |
|
||
|
||
## 7. 代码核对位置
|
||
|
||
本次对照使用以下当前代码位置作为实现依据：
|
||
|
||
- 路由注册：`server/listen/http_server/http_server.go`
|
||
- 请求上下文、登录态和 CSRF 校验：`server/listen/http_server/https_server.go`
|
||
- 登录：`server/controllers/login.go`
|
||
- 分组：`server/controllers/group.go`
|
||
- 密码修改：`server/controllers/settings.go`
|
||
- 附件：`server/controllers/attachments.go`
|
||
- 邮件列表：`server/controllers/email/list.go`
|
||
- 邮件详情：`server/controllers/email/detail.go`
|
||
- 邮件发送：`server/controllers/email/send.go`
|
||
- 统一 JSON 响应：`server/dto/response/response.go`
|
||
|
||
原版对照来源为 PMail Wiki 的《后端接口文档》。原版文档仅作为历史兼容性参考，接口是否可调用以当前 Smail 路由和处理器实现为准。 |