# 邮件系统使用指南

这是一个自托管的邮件系统，用于接收和处理电子邮件，特别适用于批量注册和验证场景。

## 系统特性

- 自动接收邮件并存储到数据库
- 提供API接口查询和管理邮件
- 支持通过邮箱地址直接查询最新邮件
- 提供验证码自动提取功能
- 支持批量注册和验证操作
- 支持邮件附件的处理和下载

## 安装和配置

### 系统要求

- Python 3.7+
- SQLite 或 MySQL 数据库
- 开放的网络端口（SMTP: 25, HTTP: 5000）

### 安装步骤

1. 克隆代码库：
```bash
git clone https://github.com/yourusername/emailsystem.git
cd emailsystem
```

2. 安装依赖：
```bash
pip install -r requirements.txt
```

3. 配置系统：
```bash
cp config.example.py config.py
# 编辑config.py文件设置相关参数
```

4. 启动系统：
```bash
python run.py --host 0.0.0.0 --port 5000 --smtp-port 25
```

5. 设置为系统服务（可选）：
```bash
sudo cp email-system.service /etc/systemd/system/
sudo systemctl enable email-system
sudo systemctl start email-system
```

## API使用指南

### 获取邮箱列表

```
GET /api/domains/{domain_id}/mailboxes
```

### 获取指定邮箱的邮件

```
GET /api/mailboxes/{mailbox_id}/emails
```

### 直接通过邮箱地址获取邮件

```
GET /api/emails/by-address?email_address=user@example.com&limit=10&unread_only=true
```

参数说明：
- `email_address`: 邮箱地址
- `limit`: 返回邮件数量限制（可选，默认10）
- `unread_only`: 是否只返回未读邮件（可选，默认false）
- `since`: 获取指定时间之后的邮件（可选，格式：YYYY-MM-DDTHH:MM:SS）

### 获取邮件详情

```
GET /api/emails/{email_id}
```

### 检查系统状态

```
GET /api/status
```

## 使用示例

### 使用API客户端

```python
from email_api_client import EmailApiClient

# 创建客户端实例
client = EmailApiClient(base_url="http://localhost:5000/api")

# 检查系统状态
status = client.check_system_status()
print(f"系统状态: {status}")

# 获取指定邮箱的最新邮件
emails = client.get_emails_by_address("user@example.com", limit=5)
print(f"获取到 {len(emails)} 封邮件")

# 等待特定邮件并提取验证码
email = client.wait_for_email(
    "user@example.com", 
    timeout=30,
    subject="验证",
    keyword="验证码"
)
if email:
    verification_code = client.extract_verification_code(email)
    print(f"验证码: {verification_code}")
```

### 运行批量注册示例

```bash
python batch_registration_example.py --domain example.com --count 10 --concurrent 3
```

## 注意事项

1. 系统需要开放25端口用于接收邮件，请确保服务器防火墙已配置
2. 默认情况下，系统会接收任何发往配置域名的邮件
3. 邮件存储在数据库中，附件存储在文件系统中
4. 系统不支持发送邮件功能

## 故障排除

1. 如果无法接收邮件，请检查：
   - SMTP端口是否开放
   - DNS MX记录是否正确配置
   - 防火墙设置
   
2. 如果API无法访问，请检查：
   - HTTP端口是否开放
   - 应用日志中是否有错误信息
   - 数据库连接是否正常

## 更多资源

- [API文档](docs/api.md)
- [配置选项](docs/configuration.md)
- [开发指南](docs/development.md)

## 维护与支持

如有问题或需要支持，请创建GitHub issue或联系维护人员。