接口文档与使用教程
点击每个接口可以展开请求参数和返回参数示例。管理后台使用管理员登录 JWT；外部调用请使用“API调用密钥”页面生成的调用密钥，并通过 X-API-Key: <密钥> 传递；需要浏览器地址栏直接访问时，也可以追加 ?api_key=<密钥>。API 调用密钥支持权限、有效期、不活跃天数和最大使用次数控制。
推荐本地测试流程： 1. GET /api/init - 初始化或自动迁移 D1 数据表 2. POST /api/auth/admin - 管理员登录后台 3. POST /api/access-key/create - 在管理后台创建 API 调用密钥，并勾选开放权限/有效期 4. 调用业务接口时在请求头加入 X-API-Key: <密钥>，或地址栏追加 ?api_key=<密钥> 5. 打开“账号管理 / 注册码管理 / 文本管理”分页查看、删除、排序并导出记录
接口总览
| 方法 | 接口 | 鉴权 | 返回格式 | 用途 |
|---|---|---|---|---|
| GET | /api/init | 无需 | JSON | 初始化或迁移 D1 数据表 |
| GET | /api/health | 无需 | JSON | 检查 API 服务是否运行 |
| GET | /api/diagnostics | 管理员 JWT | JSON | 检查 D1、KV、多实例和 Cloud-Mail 默认连接 |
| POST | /api/auth/admin | 无需 | JSON | 登录并获取 API JWT |
| POST | /api/auth/cloud/configure | 管理员 JWT / cloud:configure | JSON | 保存 Cloud-Mail 连接配置 |
| GET | /api/auth/cloud/status | 管理员 JWT / cloud:status | JSON | 查看 Cloud-Mail 连接状态 |
| GET | /api/auth/cloud/roles | 管理员 JWT / cloud:status | JSON | 读取 Cloud-Mail 可用角色，用于创建账号和注册码 |
| GET | /api/auth/cloud/domains | 管理员 JWT / cloud:status | JSON | 读取 Cloud-Mail 邮箱后缀/域名，用于创建账号 |
| GET | /api/auth/cloud/instances | 管理员 JWT | JSON | 查询多实例配置列表 |
| POST | /api/auth/cloud/instances | 管理员 JWT | JSON | 新增或更新 Cloud-Mail 实例 |
| POST | /api/auth/cloud/instances/:id/test | 管理员 JWT | JSON | 测试指定实例连接 |
| POST | /api/auth/cloud/instances/:id/default | 管理员 JWT | JSON | 设置默认实例 |
| DELETE | /api/auth/cloud/instances/:id | 管理员 JWT | JSON | 删除指定实例 |
| POST | /api/account/create | account:create | JSON/TXT | 在 Cloud-Mail 创建邮箱账号 |
| POST | /api/account/delete | account:delete | JSON/TXT | 删除 Cloud-Mail 邮箱账号 |
| GET | /api/account/list | account:list | JSON/TXT | 查询账号列表 |
| POST | /api/access-key/create | 管理员 JWT | JSON/TXT | 创建 API 调用密钥 |
| GET | /api/access-key/list | 管理员 JWT | JSON/TXT | 查询 API 调用密钥 |
| POST | /api/access-key/delete | 管理员 JWT | JSON/TXT | 删除 API 调用密钥 |
| POST | /api/key/create | 管理员 JWT / key:create | JSON/TXT | 创建注册码密钥并同步 Cloud-Mail |
| POST | /api/key/revoke | 管理员 JWT / key:delete | JSON/TXT | 禁用注册码并同步 Cloud-Mail |
| POST | /api/key/delete | 管理员 JWT / key:delete | JSON/TXT | 删除本地注册码并同步删除 Cloud-Mail 权限 |
| GET | /api/key/list | 管理员 JWT / key:list | JSON/TXT | 查询全部注册码密钥 |
| POST | /api/text/add | text:add | JSON/TXT | 新增文本内容 |
| GET | /api/text/random | text:random | TXT/JSON/XML | 随机获取文本内容 |
| GET | /api/text/list | text:list | JSON/TXT | 查询文本列表 |
| PUT | /api/text/toggle | text:toggle | JSON/TXT | 启用或禁用文本 |
| DELETE | /api/text/delete | text:delete | JSON/TXT | 删除文本 |
调用鉴权
管理页面登录后会自动使用管理员 JWT；对外接口调用统一使用管理后台创建的 API 调用密钥。推荐请求头如下，也兼容 Authorization: Key <密钥>、Authorization: ApiKey <密钥>、Authorization: Bearer <密钥>、地址栏参数 api_key 或 access_key。
X-API-Key: ak-your-api-access-key
浏览器直访示例： GET /api/text/random?api_key=ak-your-api-access-key&type=txt&response_type=txt
API 调用密钥权限可填写 all 表示全部接口，也可按需组合：account:create、account:delete、account:list、key:create、key:delete、key:list、text:random、text:add、text:list、text:delete、text:toggle、cloud:status、cloud:configure。
完整接口参数（每个字段的必传/选填、默认值、Query/Body 位置）已同步到 完整接口文档；页面下方示例保留最常用参数，方便复制测试。
POST /api/auth/admin - API 管理登录
返回 token 后用于管理后台操作，例如创建/删除 API 调用密钥和注册码密钥。外部业务调用不要分发管理员 JWT，而是分发后台创建的 API 调用密钥。
{
"username": "admin",
"password": "admin123",
"cloud_mail_url": "https://mail.example.com",
"cloud_email": "admin@example.com",
"cloud_password": "optional-cloud-password",
"cloud_token": "optional-cloud-token"
}{
"code": 200,
"message": "success",
"data": {
"token": "api-service-jwt",
"cloud_connected": true
}
}GET /api/auth/cloud/roles - 读取 Cloud-Mail 角色
管理页面会自动调用该接口，把 role_id 转成角色下拉框，避免手动填写 ID 出错。调用密钥需要 cloud:status 或 all 权限。
GET /api/auth/cloud/roles X-API-Key: ak-your-api-access-key
{
"code": 200,
"message": "success",
"data": {
"list": [
{
"role_id": 1,
"name": "普通用户",
"is_default": true
}
]
}
}GET /api/auth/cloud/domains - 读取 Cloud-Mail 邮箱域名
管理页面会自动调用该接口，把 Cloud-Mail 网站配置里的 domainList 转成账号创建页的邮箱后缀下拉框。调用密钥需要 cloud:status 或 all 权限。
GET /api/auth/cloud/domains X-API-Key: ak-your-api-access-key
{
"code": 200,
"message": "success",
"data": {
"list": ["example.com"],
"raw_list": ["@example.com"]
}
}POST /api/account/create - 创建 Cloud-Mail 账号
调用密钥必须包含 account:create 或 all 权限。支持按数量随机生成，也支持 batch_text 或 accounts 批量指定；管理页面会显示批量预览，账号管理支持勾选后批量删除。创建接口 TXT 模式返回 账号：xxx 密码：xxx，管理页导出 TXT 会使用 ---- 分隔字段。email_prefix_len 表示账号名前缀总长度：传了 email_prefix 时，会继续补随机字符直到达到该长度。
{
"email_prefix": "test",
"email_prefix_len": 8,
"email_suffix": "example.com",
"default_password": "optional-password",
"role_id": 1,
"order_id": "order_001",
"remark": "第一批测试账号",
"quantity": 2,
"batch_text": "user1@example.com,pwd123,备注一\nuser2,pwd456,备注二",
"accounts": [
{"email": "user3@example.com", "password": "pwd789", "remark": "备注三"}
],
"response_type": "json"
}{
"code": 200,
"message": "success",
"data": {
"quantity": 2,
"created": [
{
"email": "test@example.com",
"password": "pwd",
"role_id": 1,
"role_name": "普通用户",
"remark": "第一批测试账号",
"status": "created"
}
],
"summary": {
"total": 2,
"success": 2,
"failed": 0
}
}
}POST /api/account/delete 与 GET /api/account/list
删除接口需要 account:delete，列表接口需要 account:list。删除接口按邮箱批量删除；delete_scope=cloud 只删除 Cloud-Mail 并保留本地记录，delete_scope=both 会同时删除 Cloud-Mail 和 api-service 本地记录。列表接口支持分页、状态、邮箱关键字和排序。
{
"emails": ["user@example.com"],
"delete_scope": "cloud",
"response_type": "json"
}{
"code": 200,
"message": "success",
"data": {
"list": [
{
"account_id": 1,
"email": "user@example.com",
"password": "pwd",
"role_id": 1,
"role_name": "普通用户",
"status": "created",
"cloud_status": "normal",
"cloud_status_label": "正常",
"used_count": 0,
"expire_days": 0,
"cloud_user_id": "123",
"order_id": "order_001",
"created_by": "admin",
"remark": "第一批测试账号",
"error": null,
"create_time": "2026-05-17 00:00:00",
"update_time": "2026-05-17 00:00:00"
}
],
"total": 1,
"page": 1,
"size": 20
}
}POST /api/access-key/create、GET /api/access-key/list、POST /api/access-key/delete - API 调用密钥管理
这些接口只允许管理员 JWT 调用，用来创建和管理 api-service 自己的接口鉴权密钥；不会同步到 Cloud-Mail，也不会创建注册码。
{
"name": "本地测试密钥",
"prefix": "ak-",
"length": 48,
"permissions": ["account:create", "text:random"],
"max_uses": 100,
"expire_days": 30,
"inactive_days": 0,
"quantity": 1,
"response_type": "json"
}{
"code": 200,
"message": "success",
"data": {
"quantity": 1,
"keys": [
{
"access_key_id": 1,
"name": "本地测试密钥",
"key": "ak-xxxx",
"permissions": "account:create,text:random",
"max_uses": 100,
"expire_days": 30,
"inactive_days": 0
}
]
}
}GET /api/access-key/list?page=1&size=20
POST /api/access-key/delete
{
"access_key_ids": [1],
"key_values": ["ak-xxxx"]
}
POST /api/key/create - 创建 Cloud-Mail 注册码密钥
这是 Cloud-Mail 注册码密钥，不是 API 调用鉴权密钥。管理员后台可直接创建；如果用 API 调用密钥创建，则调用密钥必须包含 key:create 或 all 权限。默认随机长度为 5，支持 batch_text 或 keys 批量指定；管理页面会显示批量预览，注册码管理支持勾选后批量删除。创建接口 TXT 模式只返回注册码本身，管理页导出 TXT 会使用 ---- 分隔字段。
{
"prefix": "sk-",
"length": 5,
"role_id": 1,
"max_uses": 1,
"expire_days": 30,
"order_id": "order_001",
"remark": "第一批注册码",
"quantity": 5,
"batch_text": "sk-test-001,备注一\nsk-test-002,备注二",
"keys": [
{"key_value": "sk-test-003", "remark": "备注三"}
],
"response_type": "json"
}{
"code": 200,
"message": "success",
"data": {
"quantity": 5,
"keys": [
{
"key": "sk-xxxx",
"prefix": "sk-",
"length": 48,
"role_id": 1,
"role_name": "普通用户",
"max_uses": 1,
"available_count": 1,
"expire_days": 30,
"expire_time": "2026-06-16 00:00:00",
"remark": "第一批注册码",
"sync_status": "synced",
"sync_error": null
}
],
"synced_to_cloud": 5,
"local_only": 0,
"failed": 0
}
}POST /api/key/delete 与 GET /api/key/list
删除接口需要 API 调用密钥包含 key:delete，列表接口需要 key:list。删除时可传注册码密钥内容或 ID；delete_scope=cloud 只删除 Cloud-Mail 注册码并把本地记录标记失效，delete_scope=both 会同时删除 Cloud-Mail 和本地 D1 记录。
{
"key_values": ["sk-xxxx"],
"key_ids": [1],
"delete_scope": "both",
"response_type": "json"
}{
"code": 200,
"message": "success",
"data": {
"results": [
{
"key_id": 1,
"key_prefix": "sk-xxxx...",
"delete_scope": "both",
"deleted": true,
"local_deleted": true,
"cloud_status": "deleted",
"cloud_deleted": 1,
"cloud_error": null
}
]
}
}GET /api/key/list?page=1&size=20&sort_by=key_id&sort_order=desc&response_type=json
{
"list": [
{
"key_id": 1,
"key_value": "sk-xxxx",
"cloud_status_label": "未使用",
"role_name": "普通用户",
"used_count": 0,
"available_count": 1,
"expire_days": 30,
"expire_time": "2026-06-16 00:00:00",
"order_id": "order_001",
"created_by": "admin",
"remark": "第一批注册码",
"create_time": "2026-05-17 00:00:00"
}
],
"total": 1,
"page": 1,
"size": 20
}
POST /api/text/add、GET /api/text/random、GET /api/text/list
新增文本需要 text:add，随机读取需要 text:random，列表需要 text:list。文本类型支持 txt、json、xml；随机读取接口可通过 response_type=txt|json|xml 指定返回格式。浏览器地址栏直访时必需满足鉴权，可传 api_key 或 access_key。
{
"content": "hello cloud-mail api",
"type": "txt",
"response_type": "json"
}{
"code": 200,
"message": "success",
"data": {
"list": [
{
"text_id": 1,
"content": "hello cloud-mail api",
"type": "txt",
"status": 0,
"create_time": "2026-05-17 00:00:00"
}
],
"total": 1,
"page": 1,
"size": 20
}
}GET /api/text/random?api_key=ak-your-api-access-key&type=txt&response_type=txt GET /api/text/random?api_key=ak-your-api-access-key&type=json&response_type=json GET /api/text/random?api_key=ak-your-api-access-key&type=xml&response_type=xml