# 腾讯云SES Webhook配置指南

## 📧 **SES Webhook接口说明**

系统已创建了完整的SES webhook接口来接收腾讯云SES服务的推送数据。

### 🔗 **Webhook接口列表**

| 接口路径 | 功能描述 | 触发时机 |
|---------|---------|---------|
| `POST /api/email/send-status` | 邮件发送状态回调 | 邮件发送成功/失败时 |
| `POST /api/email/delivery-status` | 邮件投递状态回调 | 邮件投递到收件人邮箱时 |
| `POST /api/email/bounce` | 邮件退信回调 | 邮件无法投递时 |
| `POST /api/email/complaint` | 邮件投诉回调 | 收件人投诉为垃圾邮件时 |
| `POST /api/email/open` | 邮件打开事件回调 | 收件人打开邮件时 |
| `POST /api/email/click` | 邮件点击事件回调 | 收件人点击邮件链接时 |
| `POST /api/email/configuration-set` | 配置集事件回调 | 配置集状态变化时 |

### 🌐 **ngrok配置示例**

#### 1. 启动ngrok穿透后端端口8080
```bash
ngrok http 8080
```

#### 2. 获取ngrok公网地址
ngrok会显示类似：
```
Forwarding    https://abc123.ngrok.io -> http://localhost:8080
```

#### 3. 在腾讯云SES控制台配置Webhook
- 登录腾讯云SES控制台
- 进入"配置集"管理
- 添加事件发布目标
- 配置webhook URL：
  ```
  https://abc123.ngrok.io/api/email/send-status
  https://abc123.ngrok.io/api/email/delivery-status
  https://abc123.ngrok.io/api/email/bounce
  https://abc123.ngrok.io/api/email/complaint
  https://abc123.ngrok.io/api/email/open
  https://abc123.ngrok.io/api/email/click
  https://abc123.ngrok.io/api/email/configuration-set
  ```

### 📊 **接收的数据格式**

#### 邮件发送状态回调
```json
{
  "MessageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "Status": "Send",
  "Email": "user@example.com",
  "Timestamp": "2024-01-01T12:00:00.000Z"
}
```

#### 邮件退信回调
```json
{
  "MessageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "Email": "user@example.com",
  "BounceType": "Permanent",
  "BounceSubType": "General",
  "Timestamp": "2024-01-01T12:00:00.000Z"
}
```

#### 邮件投诉回调
```json
{
  "MessageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "Email": "user@example.com",
  "ComplaintType": "abuse",
  "Timestamp": "2024-01-01T12:00:00.000Z"
}
```

### 🔧 **系统处理逻辑**

#### 发送状态处理
- **Send**: 记录发送成功
- **Reject**: 记录发送被拒绝
- **Bounce**: 记录退信情况

#### 退信处理
- **硬退信**: 考虑从邮件列表移除
- **软退信**: 稍后重试发送

#### 投诉处理
- 记录投诉信息
- 检查邮件内容合规性
- 考虑移除问题邮箱

### 📝 **日志记录**

所有webhook事件都会记录到系统日志中，包括：
- 事件类型
- 邮件地址
- 时间戳
- 相关参数

### 🛡️ **安全配置**

- 所有webhook接口已配置为允许匿名访问
- 建议在生产环境中添加签名验证
- 可以添加IP白名单限制

### 🚀 **测试方法**

#### 1. 使用curl测试
```bash
curl -X POST https://your-ngrok-url.ngrok.io/api/email/send-status \
  -H "Content-Type: application/json" \
  -d '{
    "MessageId": "test-123",
    "Status": "Send",
    "Email": "test@example.com",
    "Timestamp": "2024-01-01T12:00:00.000Z"
  }'
```

#### 2. 查看日志
检查应用日志，确认webhook事件被正确处理：
```
INFO - 收到邮件发送状态回调: {MessageId=test-123, Status=Send, Email=test@example.com}
INFO - 邮件发送状态 - MessageId: test-123, Status: Send, Email: test@example.com
```

### 📋 **后续扩展**

可以根据业务需求扩展webhook处理逻辑：
1. 添加数据库存储
2. 实现邮件发送统计
3. 添加用户行为分析
4. 实现自动重试机制
5. 添加邮件模板优化建议