first commit

README.md

@@ -0,0 +1,139 @@
+# 自托管邮件系统文档
+
+## 概述
+
+这是一个自托管的邮件系统，旨在接收和处理电子邮件，特别适用于批量注册和验证场景。该系统支持通过 API 接口查询和管理邮件，并提供验证码自动提取功能。
+
+## 系统特性
+
+- 自动接收邮件并存储到 Redis 数据库
+- 提供 API 接口查询和管理邮件
+- 支持通过邮箱地址直接查询最新邮件
+- 提供验证码自动提取功能
+- 支持批量注册和验证操作
+- 支持邮件附件的处理和下载
+- 动态管理允许的域名列表
+
+## 系统架构
+
+该系统主要由以下组件构成：
+
+- **Flask**: 用于构建 Web 应用和 API 接口
+- **Redis**: 用于存储邮件数据和允许的域名列表
+- **SMTP 服务器**: 用于接收邮件
+
+## 安装和配置
+
+### 系统要求
+
+- Python 3.7+
+- Redis 数据库
+- 开放的网络端口（SMTP: 25, HTTP: 5000）
+
+### 安装步骤
+
+1. 克隆代码库：
+   ```bash
+   git clone <repository-url>
+   cd emailsystem2
+   ```
+
+2. 安装依赖：
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. 启动 Redis 服务器（确保 Redis 已安装并运行）：
+   ```bash
+   redis-server
+   ```
+
+4. 启动邮件系统：
+   ```bash
+   python run.py --host 0.0.0.0 --port 5000 --smtp-port 25
+   ```
+
+### 设置为系统服务（可选）
+
+如果希望将邮件系统设置为系统服务，可以使用以下命令：
+
+```bash
+sudo cp email-system.service /etc/systemd/system/
+sudo systemctl enable email-system
+sudo systemctl start email-system
+```
+
+## API 接口
+
+### 1. 获取最新邮件
+
+- **请求方法**: `GET`
+- **请求路径**: `/latest_email`
+- **请求参数**:
+  - `recipient`: 收件邮箱地址
+- **成功响应**:
+  ```json
+  {
+      "message_id": "<message-id>",
+      "subject": "邮件主题",
+      "sender": "发件人邮箱",
+      "recipients": ["收件人邮箱"],
+      "body": "邮件正文",
+      "timestamp": "2025-02-26T19:03:53.838745",
+      "code": "验证码"
+  }
+  ```
+
+### 2. 管理允许的域名
+
+- **添加域名**:
+  - **请求方法**: `POST`
+  - **请求路径**: `/allowed_domains/add`
+  - **请求体**:
+  ```json
+  {
+      "domain": "email.nosqli.com"
+  }
+  ```
+  - **成功响应**:
+  ```json
+  {
+      "message": "Domain added successfully"
+  }
+  ```
+
+- **删除域名**:
+  - **请求方法**: `POST`
+  - **请求路径**: `/allowed_domains/remove`
+  - **请求体**:
+  ```json
+  {
+      "domain": "email.nosqli.com"
+  }
+  ```
+  - **成功响应**:
+  ```json
+  {
+      "message": "Domain removed successfully"
+  }
+  ```
+
+- **获取当前允许的域名及其创建时间**:
+  - **请求方法**: `GET`
+  - **请求路径**: `/allowed_domains/list`
+  - **成功响应**:
+  ```json
+  {
+      "email.nosqli.com": "2025-02-26T19:03:53.838745",
+      "tw.nosqli.com": "2025-02-26T19:05:00.123456"
+  }
+  ```
+
+## 日志记录
+
+系统使用 Python 的 `logging` 模块记录操作日志，所有日志信息将输出到控制台，便于调试和监控。
+
+## 注意事项
+
+- 确保 Redis 服务器正常运行，并且网络端口未被其他服务占用。
+- 在生产环境中，建议使用 WSGI 服务器（如 Gunicorn）来运行 Flask 应用.