commit a0e9bae5a0a2561127ab1bb5439d58f7ddd6be22 Author: huangzhenpc Date: Wed Mar 26 11:37:17 2025 +0800 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..d2e831e --- /dev/null +++ b/README.md @@ -0,0 +1,289 @@ +# Outlook邮件API + +这是一个用于获取Outlook邮件的REST API服务，通过提供Outlook账户的邮箱地址、客户端ID和刷新令牌，可以获取邮箱中的最新邮件，并且能够从验证邮件中提取验证码。 + +## 功能特点 + +- 支持多个不同的Outlook邮箱账户 +- 使用Redis缓存access_token，减轻服务器负担 +- 不在服务器上持久化存储邮箱凭证 +- 支持按发件人筛选邮件 +- 自动提取邮件中的验证码 +- 自动刷新令牌并返回最新的refresh_token + +## 安装部署 + +### 安装依赖 + +```bash +pip install -r requirements.txt +``` + +### 开发环境运行 + +```bash +python mail_api.py +``` + +### 生产环境部署 + +**使用Gunicorn**: +```bash +gunicorn -w 4 -b 0.0.0.0:5000 mail_api:app +``` + +**使用Docker**: +```bash +# 构建镜像 +docker build -t outlook-email-api . + +# 运行容器 +docker run -d -p 5000:5000 \ + -e REDIS_URL=redis://your-redis-host:6379/0 \ + -e API_KEY=your_api_key \ + outlook-email-api +``` + +**使用Docker Compose**: +```bash +docker-compose up -d +``` + +## 环境变量配置 + +可以通过环境变量进行配置： + +| 环境变量 | 说明 | 默认值 | +|--------------------|----------------------------------|----------------------------| +| API_KEY | API访问密钥，用于保护API安全 | your_default_api_key | +| REDIS_URL | Redis连接URL | redis://localhost:6379/0 | +| TOKEN_CACHE_EXPIRES| access_token缓存时间（秒） | 300 | +| PORT | 服务端口 | 5000 | +| HOST | 监听地址 | 0.0.0.0 | +| DEBUG | 是否启用调试模式 | False | + +## API接口说明 + +### 1. 获取验证码 + +专门用于提取验证邮件中的验证码，默认从no-reply@cursor.sh发送的邮件中提取。 + +**URL**: `/api/verification-code` +**方法**: `POST` +**请求头**: +``` +X-API-Key: your_api_key (如果设置了API_KEY环境变量) +Content-Type: application/json +``` + +**请求体**: +```json +{ + "email": "your_outlook_email@outlook.com", + "client_id": "your_client_id", + "refresh_token": "your_refresh_token", + "folder": "INBOX", // 可选，默认为收件箱 + "sender": "no-reply@cursor.sh" // 可选，默认为"no-reply@cursor.sh" +} +``` + +**成功响应**: +```json +{ + "success": true, + "verification_code": "824026", // 提取到的验证码 + "refresh_token": "new_refresh_token" // 如果有更新 +} +``` + +**未找到验证码响应**: +```json +{ + "success": true, + "verification_code": null, + "email": { + "subject": "邮件主题", + "from": "发件人", + "body": "邮件内容", + // 其他邮件字段... + }, + "refresh_token": "new_refresh_token" +} +``` + +### 2. 获取邮件 + +获取指定邮箱的最新邮件。 + +**URL**: `/api/emails` +**方法**: `POST` +**请求头**: +``` +X-API-Key: your_api_key (如果设置了API_KEY环境变量) +Content-Type: application/json +``` + +**请求体**: +```json +{ + "email": "your_outlook_email@outlook.com", + "client_id": "your_client_id", + "refresh_token": "your_refresh_token", + "folder": "INBOX", // 可选，默认为收件箱 + "limit": 5, // 可选，默认获取5封最新邮件 + "sender": "example@example.com", // 可选，筛选特定发件人的邮件 + "latest_only": true // 可选，只返回最新的一封邮件 +} +``` + +**成功响应**: +```json +{ + "success": true, + "emails": [ + { + "subject": "邮件主题", + "from": "发件人", + "sender_email": "发件人邮箱", + "date": "日期", + "body": "邮件内容", + "attachments": ["附件名称1", "附件名称2"], // 如果有附件 + "id": "邮件ID" + } + ], + "refresh_token": "new_refresh_token" // 如果有更新 +} +``` + +### 3. 获取邮箱文件夹列表 + +获取邮箱的所有文件夹列表。 + +**URL**: `/api/folders` +**方法**: `POST` +**请求头**: +``` +X-API-Key: your_api_key (如果设置了API_KEY环境变量) +Content-Type: application/json +``` + +**请求体**: +```json +{ + "email": "your_outlook_email@outlook.com", + "client_id": "your_client_id", + "refresh_token": "your_refresh_token" +} +``` + +**成功响应**: +```json +{ + "success": true, + "folders": ["INBOX", "Sent", "Drafts", "Junk"], // 文件夹列表 + "refresh_token": "new_refresh_token" // 如果有更新 +} +``` + +### 4. 健康检查 + +检查API服务状态。 + +**URL**: `/health` +**方法**: `GET` + +**成功响应**: +```json +{ + "status": "ok", + "service": "outlook-email-api", + "redis": "ok", // Redis连接状态，"ok"或"error" + "time": "2025-03-26T12:34:56.789Z" +} +``` + +## 使用示例 + +### 示例1: 提取验证码 + +```python +import requests +import json + +# API接口地址 +url = "http://localhost:5000/api/verification-code" + +# 凭据信息 +data = { + "email": "your_outlook_email@outlook.com", + "client_id": "your_client_id", + "refresh_token": "your_refresh_token", + "sender": "no-reply@cursor.sh" +} + +headers = {"Content-Type": "application/json"} + +# 发送请求 +response = requests.post(url, json=data, headers=headers) +result = response.json() + +# 提取验证码 +if result.get("success") and result.get("verification_code"): + verification_code = result["verification_code"] + print(f"验证码: {verification_code}") +else: + print("未能获取验证码") +``` + +### 示例2: 获取最新邮件 + +```python +import requests + +# API接口地址 +url = "http://localhost:5000/api/emails" + +# 凭据信息 +data = { + "email": "your_outlook_email@outlook.com", + "client_id": "your_client_id", + "refresh_token": "your_refresh_token", + "latest_only": true +} + +headers = {"Content-Type": "application/json"} + +# 发送请求 +response = requests.post(url, json=data, headers=headers) +result = response.json() + +# 处理邮件 +if result.get("success") and result.get("emails"): + latest_email = result["emails"][0] + print(f"最新邮件: {latest_email['subject']}") + print(f"内容: {latest_email['body'][:100]}...") +``` + +## 验证码提取支持 + +目前支持多种验证码格式提取： + +1. 6位数字验证码，位于单独行并包含"This code expires"或"验证码有效期为"的文本 +2. 常规的6位数字验证码 +3. 4-8位的数字验证码 + +## 注意事项 + +1. 系统不存储任何邮箱凭证，所有请求都需要传入完整的凭证信息 +2. 刷新令牌有过期时间，API会返回新的刷新令牌（如果有） +3. 建议在生产环境中通过HTTPS提供服务以确保安全 +4. 如果传入了发件人参数，系统将只返回该发件人的最新一封邮件 + +## 部署建议 + +1. 使用HTTPS确保通信安全 +2. 设置适当的API_KEY保护接口 +3. 使用反向代理如Nginx进行流量管理 +4. 对API进行速率限制防止滥用 +5. 定期监控Redis缓存使用情况 +6. 考虑使用负载均衡器实现高可用 \ No newline at end of file