📧 云梦无限邮箱系统 - API开发文档

# API对接开发文档

API接口地址:https://ym-mail.ymmynb.com

当前版本号：1.4.1

## 文档概述

本文档详细记录了 `/api/` 目录下所有API接口的功能实现与对接规范，旨在帮助开发人员理解和集成这些接口。所有接口均为用户前台可用功能

## 接口列表

| 接口路径 | 方法 | 描述 |
|---------|------|------|
| `/api/version` | GET | 获取系统版本信息 |
| `/api/mailboxes` | GET | 获取邮箱列表 |
| `/api/mailboxes` | POST | 创建新邮箱 |
| `/api/emails` | GET | 获取邮件列表 |
| `/api/emails` | POST | 接收邮件（邮件服务器使用） |
| `/api/emails/:id` | GET | 获取邮件详情 |
| `/api/emails/:id` | DELETE | 删除邮件 |
| `/api/emails/:id/attachments/:index` | GET | 下载邮件附件 |
| `/api/domains` | GET | 获取域名配置 |
| `/api/stats` | GET | 获取统计信息 |
| `/api/emails/batch` | POST | 批量操作邮件 |

## 版本控制说明

### 版本号校验机制

所有API接口（除 `/api/version` 外）都需要在请求头中携带版本号参数：

- **请求头参数**：`x-api-version`
- **格式要求**：`x.y` 格式（如 `1.0`）
- **校验规则**：
  - 主版本号必须与服务器版本一致
  - 次版本号可以低于或等于服务器版本

### 获取版本信息 API

#### 接口基本信息
- **路径**：`/api/version`
- **方法**：GET
- **描述**：获取系统版本信息

#### 响应数据示例
```json
{
  "success": true,
  "data": {
    "number": "1.0",
    "name": "云梦无限邮箱系统",
    "description": "一个简单高效的云梦无限邮箱系统",
    "releaseDate": "2024-01-01"
  }
}
```

## 接口详情

### 1. 获取邮箱列表 API

#### 接口基本信息
- **路径**：`/api/mailboxes`
- **方法**：GET
- **描述**：获取邮箱列表，支持分页和搜索

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `page` | number | 否 | 页码，默认为1 |
| `limit` | number | 否 | 每页数量，默认为20 |
| `search` | string | 否 | 搜索关键词，支持邮箱前缀和完整地址 |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.mailboxes` | array | 邮箱列表 |
| `data.pagination` | object | 分页信息 |
| `data.pagination.page` | number | 当前页码 |
| `data.pagination.limit` | number | 每页数量 |
| `data.pagination.total` | number | 总邮箱数 |
| `data.pagination.pages` | number | 总页数 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
GET /api/mailboxes?page=1&limit=20&search=test
Headers: x-api-version: 1.0
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "mailboxes": [
      {
        "_id": "60a7b8c9d0e1f2g3h4i5j6k7",
        "prefix": "test",
        "domain": "example.com",
        "fullAddress": "test@example.com",
        "createdAt": "2023-05-20T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "pages": 1
    }
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "服务器内部错误"
}
```

### 2. 创建新邮箱 API

#### 接口基本信息
- **路径**：`/api/mailboxes`
- **方法**：POST
- **描述**：创建新邮箱

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `prefix` | string | 是 | 邮箱前缀 |
| `domainName` | string | 否 | 域名名称，不提供则使用默认域名 |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.mailbox` | object | 新创建的邮箱信息 |
| `data.mailbox.id` | string | 邮箱ID |
| `data.mailbox.prefix` | string | 邮箱前缀 |
| `data.mailbox.domain` | string | 邮箱域名 |
| `data.mailbox.fullAddress` | string | 完整邮箱地址 |
| `data.mailbox.createdAt` | string | 创建时间 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 邮箱已存在，返回现有邮箱 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
POST /api/mailboxes
Headers: x-api-version: 1.0
Content-Type: application/json

{
  "prefix": "newuser",
  "domainName": "example.com"
}
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "mailbox": {
      "id": "60a7b8c9d0e1f2g3h4i5j6k8",
      "prefix": "newuser",
      "domain": "example.com",
      "fullAddress": "newuser@example.com",
      "createdAt": "2023-05-20T10:00:00.000Z"
    }
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "邮箱前缀不能为空"
}
```

### 3. 获取邮件列表 API

#### 接口基本信息
- **路径**：`/api/emails`
- **方法**：GET
- **描述**：获取邮件列表，支持分页、筛选和搜索

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `page` | number | 否 | 页码，默认为1 |
| `limit` | number | 否 | 每页数量，默认为20 |
| `mailbox` | string | 否 | 邮箱地址，用于筛选指定邮箱的邮件 |
| `unread` | boolean | 否 | 是否仅显示未读邮件，默认为false |
| `search` | string | 否 | 搜索关键词，支持主题、发件人和正文 |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.emails` | array | 邮件列表 |
| `data.pagination` | object | 分页信息 |
| `data.pagination.page` | number | 当前页码 |
| `data.pagination.limit` | number | 每页数量 |
| `data.pagination.total` | number | 总邮件数 |
| `data.pagination.pages` | number | 总页数 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
GET /api/emails?page=1&limit=20&mailbox=test@example.com&unread=true&search=hello
Headers: x-api-version: 1.0
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "emails": [
      {
        "_id": "60a7b8c9d0e1f2g3h4i5j6k9",
        "to": "test@example.com",
        "from": "sender@example.com",
        "subject": "Hello World",
        "text": "Hello, this is a test email.",
        "read": false,
        "receivedAt": "2023-05-20T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "pages": 1
    }
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "服务器内部错误"
}
```

### 4. 接收邮件 API（邮件服务器使用）

#### 接口基本信息
- **路径**：`/api/emails`
- **方法**：POST
- **描述**：接收邮件服务器投递的邮件

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `to` | string | 是 | 收件人邮箱地址 |
| `from` | string | 是 | 发件人邮箱地址 |
| `subject` | string | 否 | 邮件主题 |
| `text` | string | 否 | 邮件纯文本内容 |
| `html` | string | 否 | 邮件HTML内容 |
| `attachments` | array | 否 | 附件数组 |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.email` | object | 新创建的邮件信息 |
| `data.isSpam` | boolean | 是否为垃圾邮件（可选） |
| `data.reason` | string | 垃圾邮件原因（可选） |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 邮件被标记为垃圾邮件 |
| 201 | 邮件接收成功 |
| 400 | 请求参数错误 |
| 404 | 收件人邮箱不存在 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
POST /api/emails
Headers: x-api-version: 1.0
Content-Type: application/json

{
  "to": "test@example.com",
  "from": "sender@example.com",
  "subject": "Test Email",
  "text": "This is a test email.",
  "html": "<p>This is a test email.</p>",
  "attachments": []
}
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "email": {
      "id": "60a7b8c9d0e1f2g3h4i5j6k9",
      "to": "test@example.com",
      "from": "sender@example.com",
      "subject": "Test Email",
      "receivedAt": "2023-05-20T10:00:00.000Z",
      "hasAttachments": false
    }
  }
}
```

**垃圾邮件响应示例**：
```json
{
  "success": true,
  "message": "邮件已被标记为垃圾邮件",
  "data": {
    "isSpam": true,
    "reason": "发件人在黑名单中"
  }
}
```

### 5. 获取邮件详情 API

#### 接口基本信息
- **路径**：`/api/emails/:id`
- **方法**：GET
- **描述**：获取邮件详情，同时将邮件标记为已读

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `id` | string | 是 | 邮件ID |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.email` | object | 邮件详情 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 404 | 邮件不存在 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
GET /api/emails/60a7b8c9d0e1f2g3h4i5j6k9
Headers: x-api-version: 1.0
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "email": {
      "_id": "60a7b8c9d0e1f2g3h4i5j6k9",
      "to": "test@example.com",
      "from": "sender@example.com",
      "subject": "Hello World",
      "text": "Hello, this is a test email.",
      "html": "<p>Hello, this is a test email.</p>",
      "attachments": [],
      "read": true,
      "receivedAt": "2023-05-20T10:00:00.000Z"
    }
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "邮件不存在"
}
```

### 6. 删除邮件 API

#### 接口基本信息
- **路径**：`/api/emails/:id`
- **方法**：DELETE
- **描述**：删除指定邮件

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `id` | string | 是 | 邮件ID |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `message` | string | 成功信息 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 404 | 邮件不存在 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
DELETE /api/emails/60a7b8c9d0e1f2g3h4i5j6k9
Headers: x-api-version: 1.0
```

**成功响应示例**：
```json
{
  "success": true,
  "message": "邮件删除成功"
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "邮件不存在"
}
```

### 7. 获取域名配置 API

#### 接口基本信息
- **路径**：`/api/domains`
- **方法**：GET
- **描述**：获取所有启用的域名配置

#### 请求参数
无

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.domains` | array | 域名列表 |
| `data.defaultDomain` | string | 默认域名 |
| `data.total` | number | 域名总数 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
GET /api/domains
Headers: x-api-version: 1.0
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "60a7b8c9d0e1f2g3h4i5j6k0",
        "name": "example.com",
        "enabled": true,
        "createdAt": "2023-05-20T10:00:00.000Z"
      }
    ],
    "defaultDomain": "example.com",
    "total": 1
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "服务器内部错误"
}
```

### 8. 获取统计信息 API

#### 接口基本信息
- **路径**：`/api/stats`
- **方法**：GET
- **描述**：获取系统统计信息

#### 请求参数
无

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.totalEmails` | number | 总邮件数 |
| `data.totalMailboxes` | number | 总邮箱数 |
| `data.unreadEmails` | number | 未读邮件数 |
| `data.totalDomains` | number | 域名总数 |
| `data.recentEmails24h` | number | 最近24小时邮件数 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
GET /api/stats
Headers: x-api-version: 1.0
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "totalEmails": 100,
    "totalMailboxes": 10,
    "unreadEmails": 20,
    "totalDomains": 1,
    "recentEmails24h": 5
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "服务器内部错误"
}
```

### 9. 批量操作 API

#### 接口基本信息
- **路径**：`/api/emails/batch`
- **方法**：POST
- **描述**：批量操作邮件，支持标记已读、标记未读和删除

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `action` | string | 是 | 操作类型：markAsRead、markAsUnread、delete |
| `emailIds` | array | 是 | 邮件ID数组 |

#### 响应数据
| 字段名 | 类型 | 说明 |
|--------|------|------|
| `success` | boolean | 请求是否成功 |
| `data` | object | 响应数据 |
| `data.action` | string | 操作类型 |
| `data.affectedCount` | number | 受影响的邮件数 |
| `error` | string | 错误信息（仅当success为false时） |

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
POST /api/emails/batch
Headers: x-api-version: 1.0
Content-Type: application/json

{
  "action": "markAsRead",
  "emailIds": ["60a7b8c9d0e1f2g3h4i5j6k9", "60a7b8c9d0e1f2g3h4i5j6k0"]
}
```

**成功响应示例**：
```json
{
  "success": true,
  "data": {
    "action": "markAsRead",
    "affectedCount": 2
  }
}
```

**失败响应示例**：
```json
{
  "success": false,
  "error": "参数不完整"
}
```

### 10. 下载邮件附件 API

#### 接口基本信息
- **路径**：`/api/emails/:id/attachments/:index`
- **方法**：GET
- **描述**：下载指定邮件的附件

#### 请求参数
| 字段名 | 类型 | 是否必填 | 说明 |
|--------|------|----------|------|
| `id` | string | 是 | 邮件ID |
| `index` | number | 是 | 附件索引（从0开始） |

#### 响应数据
- **成功**：返回附件文件内容，设置相应的Content-Type和Content-Disposition头
- **失败**：返回JSON格式的错误信息

#### 状态码
| 状态码 | 含义 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 404 | 邮件不存在或附件不存在 |
| 500 | 服务器内部错误 |

#### 接口调用示例

**请求示例**：
```bash
GET /api/emails/60a7b8c9d0e1f2g3h4i5j6k9/attachments/0
Headers: x-api-version: 1.0
```

**成功响应示例**：
- 响应头：
  ```
  Content-Type: application/pdf
  Content-Disposition: attachment; filename="document.pdf"
  Content-Length: 1024000
  ```
- 响应体：文件二进制数据

**失败响应示例**：
```json
{
  "success": false,
  "error": "附件不存在"
}
```

## 错误码说明

| 错误码 | 含义 |
|--------|------|
| 400 | 请求参数错误，如邮箱前缀不能为空、选择的域名不存在或未启用、参数不完整、不支持的操作类型、缺少版本号参数、版本号格式错误、版本不兼容等 |
| 404 | 资源不存在，如邮件不存在、附件不存在、收件人邮箱不存在 |
| 500 | 服务器内部错误 |

## 特殊业务逻辑说明及注意事项

1. **版本号校验**：
   - 所有API接口（除 `/api/version` 外）都需要在请求头中携带 `x-api-version` 参数
   - 版本号格式为 `x.y`，主版本号必须与服务器一致，次版本号可以低于或等于服务器版本
   - 版本不兼容时会返回错误提示

2. **CORS中间件**：所有API接口都支持跨域请求，设置了允许所有来源的CORS头。

3. **域名处理**：
   - 创建邮箱时，如果未指定域名，会使用默认域名（第一个启用的域名）
   - 如果指定了域名，会检查该域名是否存在且已启用
   - 如果邮箱已存在，会返回现有邮箱信息（状态码200）

4. **邮件处理**：
   - 获取邮件详情时，会自动将邮件标记为已读
   - 获取邮件列表时，默认不返回HTML内容和附件二进制数据，以提高响应速度
   - 接收邮件时会自动进行垃圾邮件检测和过滤

5. **垃圾邮件过滤**：
   - 自动检测发件人和域名是否在黑名单中
   - 检测同一发件人、同一主题的邮件数量（最近24小时）
   - 检测同一发件人域名的重复内容邮件数量（最近24小时）
   - 超过阈值会自动标记为垃圾邮件或拉黑

6. **分页处理**：所有列表接口都支持分页，默认每页20条数据

7. **搜索功能**：
   - 邮箱列表支持按前缀和完整地址搜索
   - 邮件列表支持按主题、发件人和正文搜索

8. **批量操作**：支持批量标记邮件已读/未读和批量删除邮件

9. **统计信息**：包含总邮件数、总邮箱数、未读邮件数、域名总数和最近24小时邮件数

10. **附件处理**：
    - 邮件支持附件，附件信息包含在邮件详情中
    - 附件下载通过专门的API接口实现
    - 支持多种文件类型的附件下载




## 总结

本API提供了完整的邮箱管理功能，包括邮箱的创建和查询、邮件的接收和管理、域名配置的获取以及系统统计信息的查询。所有接口均为用户前台可用功能，无需管理员权限。开发人员可以根据本文档的规范对接这些接口，实现邮件系统的集成。使用时请注意版本号校验机制，确保客户端版本与服务器版本兼容。