docs: Add a comprehensive API usage guide by ID-VerNe · Pull Request #306 · maillab/cloud-mail

ID-VerNe · 2026-03-31T10:05:12Z

This PR adds a detailed API guide in the 'doc' folder to help developers and users understand how to interact with the backend programmatically. It includes authentication, email operations, and public token generation steps.

Copilot

Pull request overview

This PR adds a new, detailed API usage guide under doc/ to help external scripts and automation interact with the Cloud Mail backend.

Changes:

Added doc/API_GUIDE.md covering auth, account management, email operations, and Public Token usage
Included example requests and a JavaScript snippet for scripted consumption
Added operational notes about token reuse and Cloudflare free-tier quota considerations

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T10:09:16Z

+### 2.2 用户注册
+- **方法**: `POST`
+- **路径**: `/register`
+- **请求体**: `{ "email": "user@example.com", "password": "password", "regKey": "optional_key" }`


/register 的请求体字段与后端实现不一致：后端 loginService.register 读取的是 email/password/token/code（其中 code 用作注册码/注册Key），文档里写成了 regKey 且未提到可能需要的 token（Turnstile）。建议按实际参数名更新示例与说明。

Suggested change

- **请求体**: `{ "email": "user@example.com", "password": "password", "regKey": "optional_key" }`

- **请求体 (JSON)**:

```json

{

"email": "user@example.com",

"password": "password",

"token": "turnstile_token_optional",

"code": "optional_reg_code"

}

Copilot · 2026-03-31T10:09:17Z

+### 3.2 创建新邮箱 (Prefix)
+- **方法**: `POST`
+- **路径**: `/account/add`
+- **请求体**: `{ "account": "new_prefix" }` (只需填前缀)


/account/add 的请求体与后端不一致：后端 accountService.add 期望参数名为 email（完整邮箱地址），并可能需要 token（Turnstile）用于校验；文档写成 { "account": "new_prefix" } 且说明“只需填前缀”。这会导致按文档调用直接失败，建议改为与实际接口一致并说明是否需要携带验证码 token。

Suggested change

- **请求体**: `{ "account": "new_prefix" }` (只需填前缀)

- **请求体**: `{ "email": "new_prefix@your-domain.com", "token": "TURNSTILE_TOKEN" }`（`email` 为完整邮箱地址，`token` 为 Turnstile 验证值，如开启验证码校验时必填）

Copilot · 2026-03-31T10:09:17Z

+### 3.3 删除邮箱
+- **方法**: `DELETE`
+- **路径**: `/account/delete`
+- **查询参数**: `?id=ACCOUNT_ID`


/account/delete 的查询参数写成了 ?id=ACCOUNT_ID，但后端与前端调用使用的是 accountId（见 mail-worker/src/service/account-service.js 与 mail-vue/src/request/account.js）。建议将参数名改为 accountId，避免调用 400/无法删除。

Suggested change

- **查询参数**: `?id=ACCOUNT_ID`

- **查询参数**: `?accountId=ACCOUNT_ID`

Copilot · 2026-03-31T10:09:17Z

+- **查询参数**:
+  - `page`: 页码 (默认1)
+  - `size`: 每页数量 (默认20)
+  - `accountId`: 可选，指定查看某个邮箱账号的邮件


邮件列表接口 /email/list 的参数说明与后端不一致：后端 emailService.list 使用的是游标式参数（如 emailId/size/timeSort/accountId/type/allReceive），并不支持文档里描述的 page 分页；且 type/accountId 等对结果有决定性影响。建议按实际实现更新查询参数与示例，否则按文档调用可能一直返回空列表或报错。

Suggested change

- **查询参数**:

- `page`: 页码 (默认1)

- `size`: 每页数量 (默认20)

- `accountId`: 可选，指定查看某个邮箱账号的邮件

- **说明**: 使用游标式分页，不支持 `page` 页码参数。通常先不带 `emailId` 拉取最新一批邮件，然后使用上一批结果中最后一封邮件的 `id` 作为下一次的 `emailId` 继续向后翻页。

- **查询参数**:

- `emailId`: 可选，游标起点邮件 ID；为空时从最新邮件开始

- `size`: 每次返回的邮件数量 (默认 20)

- `timeSort`: 排序方向，`desc` 表示按时间倒序（最新在前），`asc` 表示按时间正序

- `accountId`: 可选，指定查看某个邮箱账号的邮件；不传时视实现可能返回默认账号或全部账号

- `type`: 可选，邮件类型/文件夹，例如 `INBOX`/`SENT`/`TRASH` 等，具体取值以实际实现为准

- `allReceive`: 可选，布尔值，是否拉取所有接收的邮件（如多账号聚合），例如 `true`/`false`

Copilot · 2026-03-31T10:09:17Z

+    "from": "sender@your-domain.com",
+    "to": "target@external.com",
+    "subject": "Email Subject",
+    "content": "<h1>HTML Content</h1>",
+    "attIds": [] 


/email/send 的请求体字段与后端实现不一致：后端 emailService.send 接收 accountId/receiveEmail/name/subject/content/text/sendType/emailId/attachments 等字段，文档示例使用了 from/to/attIds。建议按实际字段更新，并明确 receiveEmail 是否为数组及附件字段格式，否则脚本调用无法发送邮件。

Suggested change

"from": "sender@your-domain.com",

"to": "target@external.com",

"subject": "Email Subject",

"content": "<h1>HTML Content</h1>",

"attIds": []

"accountId": "ACCOUNT_ID",

"receiveEmail": ["target1@external.com", "target2@external.com"],

"name": "Sender Name",

"subject": "Email Subject",

"content": "<h1>HTML Content</h1>",

"text": "Plain text content",

"sendType": "NORMAL",

"emailId": null,

"attachments": ["ATTACHMENT_ID_1", "ATTACHMENT_ID_2"]

Copilot · 2026-03-31T10:09:18Z

+### 4.3 彻底删除邮件
+- **方法**: `DELETE`
+- **路径**: `/email/delete`
+- **参数**: `?id=EMAIL_ID`


/email/delete 的参数写成了 ?id=EMAIL_ID，但后端 emailService.delete 实际读取的是 emailIds（逗号分隔的 ID 列表）。建议将文档参数改为 emailIds 并说明支持批量删除。

Suggested change

- **参数**: `?id=EMAIL_ID`

- **参数**: `?emailIds=EMAIL_ID1,EMAIL_ID2,...` （逗号分隔的邮件 ID 列表，支持批量删除，也可仅传单个 ID）

Copilot · 2026-03-31T10:09:18Z

+### 5.2 使用 Public Token 获取指定邮箱邮件列表
+- **方法**: `POST`
+- **路径**: `/public/emailList`
+- **请求体**: `{ "account": "target@your-domain.com" }`


/public/emailList 的请求体与后端 publicService.emailList 不一致：后端并没有 account 字段，而是通过 toEmail/sendEmail/subject/content/num/size/type/isDel 等过滤与分页参数查询。建议按实际参数更新，否则使用 Public Token 调用会拿不到预期数据。

Suggested change

- **请求体**: `{ "account": "target@your-domain.com" }`

- **请求体 (JSON)**：

```json

{

"toEmail": "target@your-domain.com", // 收件邮箱（可选筛选条件）

"sendEmail": "sender@example.com", // 发件邮箱（可选筛选条件）

"subject": "keyword", // 主题关键词（可选）

"content": "content keyword", // 正文关键词（可选）

"type": 0, // 邮件类型（可选，按后端约定值）

"isDel": 0, // 是否已删除（可选，0=未删除，1=已删除）

"num": 1, // 页码，从 1 开始

"size": 20 // 每页数量

}

Copilot · 2026-03-31T10:09:18Z

+1.  **登录**: 调用 `POST /api/login`，传入非管理员的账号和密码。
+2.  **权限限制**: 非管理员无法访问 `/api/user/**` 或 `/api/allEmail/**` 等管理类接口，但可以正常管理自己名下的临时邮箱地址和接收邮件。
+3.  **注册**: 如果系统开启了注册功能，可以通过 `POST /api/register` 创建非管理员账户。


同一文档中路径前缀的写法不一致：前文已定义 API 根路径为 .../api 且接口路径如 /login，但本节又写成 POST /api/login、POST /api/register。建议统一约定（例如始终写“根路径 + 相对路径”），避免读者重复拼接导致请求变成 /api/api/login。

Suggested change

1. **登录**: 调用 `POST /api/login`，传入非管理员的账号和密码。

2. **权限限制**: 非管理员无法访问 `/api/user/**` 或 `/api/allEmail/**` 等管理类接口，但可以正常管理自己名下的临时邮箱地址和接收邮件。

3. **注册**: 如果系统开启了注册功能，可以通过 `POST /api/register` 创建非管理员账户。

1. **登录**: 调用 `POST /login`，传入非管理员的账号和密码。

2. **权限限制**: 非管理员无法访问 `/user/**` 或 `/allEmail/**` 等管理类接口，但可以正常管理自己名下的临时邮箱地址和接收邮件。

3. **注册**: 如果系统开启了注册功能，可以通过 `POST /register` 创建非管理员账户。

Copilot · 2026-03-31T10:09:18Z

+| 功能 | 方法 | 路径 | 参数 |
+| :--- | :--- | :--- | :--- |
+| 获取所有用户 | `GET` | `/user/list` | `?page=1&size=20` |
+| 设置用户密码 | `PUT` | `/user/setPwd` | `{ "userId": "xx", "password": "xx" }` |
+| 重置发送计数 | `PUT` | `/user/resetSendCount` | `{ "userId": "xx" }` |
+| 查看全站邮件 | `GET` | `/allEmail/list` | `?page=1` |
+


管理员接口列表的 Markdown 表格每行以 || 开头/结尾，渲染时会多出空列或无法正确对齐。建议改为标准 Markdown 表格格式（每行单个 | 分隔列）。

docs: add comprehensive API usage guide

6323155

Copilot AI review requested due to automatic review settings March 31, 2026 10:05

Copilot started reviewing on behalf of ID-VerNe March 31, 2026 10:05 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

ID-VerNe added 2 commits March 31, 2026 18:24

docs: refine API guide with troubleshooting and best practices

e06feb3

docs: restore full API reference and finalize integration guide

920d902

ID-VerNe closed this Mar 31, 2026

ID-VerNe reopened this Mar 31, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add a comprehensive API usage guide#306

docs: Add a comprehensive API usage guide#306
ID-VerNe wants to merge 3 commits intomaillab:mainfrom
ID-VerNe:feature/add-api-guide

ID-VerNe commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- 请求体: `{ "account": "new_prefix" }` (只需填前缀)
	- 请求体: `{ "email": "new_prefix@your-domain.com", "token": "TURNSTILE_TOKEN" }`（`email` 为完整邮箱地址，`token` 为 Turnstile 验证值，如开启验证码校验时必填）

	- 查询参数: `?id=ACCOUNT_ID`
	- 查询参数: `?accountId=ACCOUNT_ID`

-- **查询参数**:
-  - `page`: 页码 (默认1)
-  - `size`: 每页数量 (默认20)
-  - `accountId`: 可选，指定查看某个邮箱账号的邮件
+- **说明**: 使用游标式分页，不支持 `page` 页码参数。通常先不带 `emailId` 拉取最新一批邮件，然后使用上一批结果中最后一封邮件的 `id` 作为下一次的 `emailId` 继续向后翻页。
+- **查询参数**:
+  - `emailId`: 可选，游标起点邮件 ID；为空时从最新邮件开始
+  - `size`: 每次返回的邮件数量 (默认 20)
+  - `timeSort`: 排序方向，`desc` 表示按时间倒序（最新在前），`asc` 表示按时间正序
+  - `accountId`: 可选，指定查看某个邮箱账号的邮件；不传时视实现可能返回默认账号或全部账号
+  - `type`: 可选，邮件类型/文件夹，例如 `INBOX`/`SENT`/`TRASH` 等，具体取值以实际实现为准
+  - `allReceive`: 可选，布尔值，是否拉取所有接收的邮件（如多账号聚合），例如 `true`/`false`

	- 参数: `?id=EMAIL_ID`
	- 参数: `?emailIds=EMAIL_ID1,EMAIL_ID2,...` （逗号分隔的邮件 ID 列表，支持批量删除，也可仅传单个 ID）

-- **请求体**: `{ "account": "target@your-domain.com" }`
+- **请求体 (JSON)**：
+  ```json
+  {
+    "toEmail": "target@your-domain.com",      // 收件邮箱（可选筛选条件）
+    "sendEmail": "sender@example.com",        // 发件邮箱（可选筛选条件）
+    "subject": "keyword",                     // 主题关键词（可选）
+    "content": "content keyword",             // 正文关键词（可选）
+    "type": 0,                                // 邮件类型（可选，按后端约定值）
+    "isDel": 0,                               // 是否已删除（可选，0=未删除，1=已删除）
+    "num": 1,                                 // 页码，从 1 开始
+    "size": 20                                // 每页数量
+  }

Conversation

ID-VerNe commented Mar 31, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants