first commit

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. 考虑使用负载均衡器实现高可用