邮件管理系统 API 文档
面向开发者的 RESTful API 说明，包含鉴权方式、统一返回格式、错误码说明以及完整接口列表。
快速开始
- 在「客户中心 → API信息」中查看并复制 API 密钥（API Key）。
- 选择需要调用的接口（如
GET /api/mailboxes获取邮箱列表）。 - 在请求头中带上
X-API-Key，并按文档中的参数说明构造请求。 - 根据返回的
code、msg和data处理业务逻辑。
基础地址（Base URL）：
http(s)://你的部署域名例如：https://mail.example.com/api/mailboxes
文档与实现：本页面描述的公开 API（/api/ 下邮箱、邮件、域名等）与后端实现已对齐，按文档开发的第三方软件可正常使用；所有需 API Key 的接口均按该密钥对应账户的套餐进行限额校验。
认证方式
1. API Key 认证（公开 API：/api/...）
公开 API（如邮箱管理、邮件管理、域名管理）需要在请求头中携带 API 密钥：
X-API-Key: your_api_key_here- API Key 可在客户中心「API信息」中获取。
- 可通过请求头、Bearer Token 或查询参数三种方式携带：
- 请求头：
X-API-Key: YOUR_API_KEY - Bearer：
Authorization: Bearer YOUR_API_KEY - 查询参数：
?api_key=YOUR_API_KEY
- 请求头：
按秘钥账户的套餐限制
使用 API 密钥调用的接口严格按该密钥对应客户账户的套餐进行限制。包括：
- 套餐是否过期（过期后无法创建邮箱）
- 独立创建数量上限（
single_limit） - 批量创建数量与单次批量上限（
batch_limit、batch_register_limit） - 邮箱总数量上限（
mailbox_limit）
创建邮箱时若超出限制或套餐过期，将返回 code: 400 及相应 msg（如「您的套餐已过期」「独立创建邮箱数量已达上限」等）。其他只读接口（如获取列表、获取邮件）不受套餐数量限制，但均需有效 API Key。
2. 客户 / 管理 API 认证（/api/customer/...、/api/admin/...）
客户和管理 API 通常在登录客户中心 / 管理后台后，通过 Cookie 会话完成认证，无需单独传 Token。
如需在第三方系统中直接调用，可在登录接口获取 JWT Token，并在请求头中携带：
Authorization: Bearer your_jwt_token_hereJWT 默认有效期为 24 小时，过期后需要重新登录获取。
统一响应格式
所有接口（除少数文件/HTML返回外）均返回统一 JSON 结构：
{
"code": 0, // 业务状态码：0 表示成功，非 0 表示失败
"msg": "success", // 描述信息：成功时为说明文字，失败时为错误原因
"data": {...}, // 返回数据，结构因接口而异
"timestamp": 1234567890 // 服务器时间戳（秒）
}常见业务状态码：
0：成功。400：参数错误 / 业务校验失败（例如：邮箱已存在、配额不足、格式不正确）。401：未认证（例如：未登录、API Key 无效）。403：已认证但无权限（例如：账号被封禁、API 已禁用）。404：资源不存在（例如：邮箱不存在）。500：服务器内部错误或下游邮件系统错误。
HTTP 状态码通常为 200，业务错误通过 code 字段表示。
邮箱管理 API
需要 API Key 认证
/api/mailboxes
获取邮箱列表
参数（均为 Query）：
page- 页码（默认 1）size- 每页数量（默认 20）domain- 按域名筛选（可选）
响应： data 为下游邮件系统（宝塔插件）返回的原始结构，通常包含邮箱列表及分页信息，以实际返回为准。
{
"code": 0,
"msg": "获取成功",
"data": { ... },
"timestamp": 1234567890
}/api/mailbox
查询单个邮箱
参数（Query）：
username- 邮箱地址（必填）
响应： data 为下游邮件系统返回的单个邮箱信息，可能包含 username、full_name、quota、status 等字段。
{
"code": 0,
"msg": "获取成功",
"data": { "username": "user@example.com", "full_name": "用户", "quota": "5 GB", "status": 1, ... },
"timestamp": 1234567890
}/api/mailboxes
创建邮箱
请求体：
{
"username": "user@example.com",
"password": "Abc123!@#",
"full_name": "用户",
"quota": "5 GB"
}参数说明：
username- 邮箱地址（必填，不能含大写字母）password- 密码（必填，宝塔要求：大写+小写+数字+特殊字符，如 Abc123!@#）full_name- 显示名称（必填）quota- 容量，支持 "5 GB"、"5GB"、"5" 等，默认 5GB（可选）
注意：邮箱会同步到宝塔邮局，若宝塔返回失败（如参数不符合要求），本系统不会写入本地记录。
响应示例：
{
"code": 0,
"msg": "创建成功",
"data": {
"username": "user@example.com"
},
"timestamp": 1234567890
}/api/mailboxes
删除邮箱
参数（Query）：
username- 邮箱地址（必填）
响应示例：
{
"code": 0,
"msg": "删除成功",
"data": { ... },
"timestamp": 1234567890
}/api/mailboxes/batch
批量创建邮箱
请求体：
[
{
"username": "user1@example.com",
"password": "Abc123!@#",
"full_name": "用户1",
"quota": "5 GB"
},
{
"username": "user2@example.com",
"password": "Def456!@#",
"full_name": "用户2",
"quota": "5"
}
]参数说明：
- 与单条创建相同，
username不能含大写，password需符合宝塔要求（大写+小写+数字+特殊字符）。
响应示例：
{
"code": 0,
"msg": "批量创建完成",
"data": {
"success_count": 2,
"failed_count": 0,
"success": ["user1@example.com", "user2@example.com"],
"failed": []
},
"timestamp": 1234567890
}/api/mailboxes/batch
批量删除邮箱
请求体：
{
"usernames": ["user1@example.com", "user2@example.com"]
}响应示例：
{
"code": 0,
"msg": "批量删除完成",
"data": {
"success_count": 2,
"failed_count": 0,
"success": ["user1@example.com", "user2@example.com"],
"failed": []
},
"timestamp": 1234567890
}邮件管理 API
需要 API Key 认证
/api/mails/inbox
获取收件箱
参数（Query）：
username- 邮箱地址（必填）page- 页码（默认 1）
响应： data 为下游邮件系统返回的收件列表结构。
{
"code": 0,
"msg": "获取成功",
"data": { ... },
"timestamp": 1234567890
}/api/mails/sent
获取已发送邮件
参数（Query）： username（必填）、page（默认 1）。
/api/mails/junk
获取垃圾箱
参数（Query）： username（必填）、page（默认 1）。
/api/mails/content
获取邮件内容
参数（Query）： path - 邮件路径（必填）。
/api/mails/send
发送邮件
请求体：
{
"mail_from": "sender@example.com",
"mail_to": ["receiver1@example.com", "receiver2@example.com"],
"subject": "邮件主题",
"content": "邮件内容",
"subtype": "html"
}参数说明：
mail_from- 发件人邮箱（必填）mail_to- 收件人邮箱数组（必填）subject- 邮件主题（必填）content- 邮件内容（必填）subtype- 内容类型，可选值：html、plain（默认 html，可选）
/api/mails
删除单封邮件
参数（Query）： path - 邮件路径（必填）。
/api/mails/batch
批量删除邮件
请求体（JSON）：
{
"paths": ["/path/to/mail1", "/path/to/mail2"]
}/api/mails/mark-junk
标记垃圾邮件
参数（Query）： path（必填）、username（必填）。
/api/mails/unmark-junk
取消标记垃圾邮件
参数（Query）： path（必填）、username（必填）。
域名管理 API
需要 API Key 认证
/api/domains
获取域名列表
参数：
page- 页码（默认1）size- 每页数量（默认20）
返回系统中所有可用的邮件域名。
客户 API
需要 JWT Token 认证
/api/customer/domains
获取可用域名列表
返回客户可用的邮件域名列表。
/api/customer/mailboxes
获取客户邮箱列表
参数：
page- 页码（默认1）size- 每页数量（默认20）
/api/customer/mail-config
获取邮件配置
返回邮件系统配置，包括自动刷新间隔等。
/api/customer/package-status
套餐状态检查
返回客户当前套餐状态信息。
/api/customer/recharge-plans
获取充值方案
返回系统中可用的充值方案列表。
/api/customer/mails
获取客户邮件列表
参数：
mailbox- 邮箱地址（必填）type- 邮件类型：inbox、sent、junk（默认inbox）page- 页码（默认1）
/api/customer/mails/search
搜索客户邮件
参数：
keyword- 搜索关键词（必填）mailbox- 邮箱地址（必填）type- 邮件类型：inbox、sent、junk（默认inbox）
/api/customer/mails/content
获取客户邮件内容
参数：
path- 邮件路径（必填）
/api/customer/mails/:id
获取客户邮件详情
参数：
id- 邮件ID（必填，从URL路径获取）
/api/customer/mails/:id/read
标记客户邮件为已读
参数：
id- 邮件ID（必填，从URL路径获取）
/api/customer/mails/send
发送客户邮件
请求体：
{
"From": "sender@example.com",
"To": ["receiver@example.com"],
"Subject": "邮件主题",
"Content": "邮件内容",
"Subtype": "html"
}/api/customer/mails/delete
删除客户邮件
请求体：
{
"mail_ids": ["/path/to/mail1", "/path/to/mail2"]
}/api/customer/nickname
更新客户昵称
请求体：
{
"nickname": "新昵称"
}/api/customer/avatar
上传客户头像
请求体：
multipart/form-data 格式，包含字段：
avatar- 头像文件（必填）
/api/customer/password
修改密码
请求体：
{
"old_password": "旧密码",
"new_password": "新密码"
}/api/customer/api-key
更新客户API密钥
生成新的API密钥并返回。
管理 API
需要管理员 JWT Token 认证
/api/admin/domains
获取域名列表
参数：
page- 页码（默认1）size- 每页数量（默认20）
/api/admin/mails
获取邮件列表
参数：
page- 页码（默认1）size- 每页数量（默认20）
/api/admin/profile
获取管理员个人资料
/api/admin/profile
更新管理员个人资料
请求体：
{
"nickname": "新昵称",
"email": "admin@example.com"
}/api/admin/profile/password
修改管理员密码
请求体：
{
"old_password": "旧密码",
"new_password": "新密码"
}错误码详情
0- 成功：操作已完成。400- 参数错误 / 业务失败：- 参数缺失或格式不正确（例如
username必填）。 - 邮箱已存在 / 不存在。
- 套餐或配额限制（如「独立创建数量已达上限」）。
- 参数缺失或格式不正确（例如
401- 未认证：- 未登录客户中心或管理后台。
- API 密钥为空或无效。
403- 无权限：- 账号被封禁。
- API 密钥被禁用。
404- 资源不存在（如查询不存在的邮箱或邮件）。500- 服务器内部错误或下游邮件系统异常。
具体原因请查看返回中的 msg 字段，例如：「邮箱已存在」「您的套餐已过期，请续费后再创建邮箱」。