first commit
This commit is contained in:
huangzhenpc
289
README.md
Normal file
289
README.md
Normal file
@@ -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. 考虑使用负载均衡器实现高可用
|
||||
Reference in New Issue
Block a user