Files
outlookapi/README.md
huangzhenpc a0e9bae5a0 first commit
2025-03-26 11:37:17 +08:00

289 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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