AIGC/demo/TENCENT_SES_WEBHOOK_DESIGN.md

# 腾讯云SES邮件验证回调路径设计

## 📧 **回调接口设计**

### 🔗 **回调地址**
```
POST /api/tencent/ses/webhook
```

### 🌐 **完整URL示例**
```
https://your-domain.com/api/tencent/ses/webhook
```

## 🔧 **腾讯云控制台配置**

### 1️⃣ **配置步骤**
1. 登录腾讯云邮件推送控制台
2. 导航至"邮件配置" > "回调配置" > "回调地址配置"
3. 选择回调级别：
   - **账户级回调**：对该账户下所有发信地址生效
   - **发信地址级回调**：仅对指定发信地址生效（优先级更高）
4. 输入回调地址：`https://your-domain.com/api/tencent/ses/webhook`
5. 保存配置

### 2️⃣ **端口要求**
- 仅支持端口：**8080**, **8081**, **8082**
- 必须使用HTTPS协议
- 确保回调地址可公网访问

## 📊 **支持的事件类型**

| 事件类型 | 描述 | 触发时机 |
|---------|------|---------|
| `delivery` | 递送成功 | 邮件成功送达收件人邮箱 |
| `reject` | 腾讯云拒信 | 由于腾讯云策略原因被拒绝发送 |
| `bounce` | ESP退信 | 邮件被收件人邮箱服务提供商退回 |
| `open` | 用户打开邮件 | 收件人打开了邮件 |
| `click` | 点击链接 | 收件人点击了邮件中的链接 |
| `unsubscribe` | 退订 | 收件人选择退订邮件 |

## 📝 **回调数据格式**

### 基础数据结构
```json
{
  "eventType": "delivery",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

### 递送成功事件
```json
{
  "eventType": "delivery",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

### 拒信事件
```json
{
  "eventType": "reject",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "reason": "Content policy violation",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

### 退信事件
```json
{
  "eventType": "bounce",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "bounceType": "Permanent",
  "bounceSubType": "General",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

### 打开事件
```json
{
  "eventType": "open",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "userAgent": "Mozilla/5.0...",
  "ipAddress": "192.168.1.1"
}
```

### 点击事件
```json
{
  "eventType": "click",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "link": "https://example.com/click",
  "userAgent": "Mozilla/5.0...",
  "ipAddress": "192.168.1.1"
}
```

### 退订事件
```json
{
  "eventType": "unsubscribe",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "unsubscribeType": "one-click"
}
```

## 🔒 **安全验证**

### 请求头验证
```http
X-Tencent-Token: your-token
X-Tencent-Timestamp: 1640995200
X-Tencent-Signature: calculated-signature
```

### 签名验证流程
1. 获取请求头中的Token、时间戳、签名
2. 验证时间戳（防止重放攻击）
3. 使用预共享密钥计算签名
4. 对比签名是否一致

## 🚀 **ngrok测试配置**

### 1️⃣ **启动ngrok**
```bash
# 穿透后端端口8080
ngrok http 8080
```

### 2️⃣ **获取公网地址**
```
Forwarding    https://abc123.ngrok.io -> http://localhost:8080
```

### 3️⃣ **配置回调地址**
```
https://abc123.ngrok.io/api/tencent/ses/webhook
```

### 4️⃣ **测试回调**
```bash
curl -X POST https://abc123.ngrok.io/api/tencent/ses/webhook \
  -H "Content-Type: application/json" \
  -H "X-Tencent-Token: test-token" \
  -H "X-Tencent-Timestamp: 1640995200" \
  -H "X-Tencent-Signature: test-signature" \
  -d '{
    "eventType": "delivery",
    "messageId": "test-123",
    "email": "test@example.com",
    "timestamp": "2024-01-01T12:00:00.000Z"
  }'
```

## 📋 **业务处理逻辑**

### 递送成功处理
- 更新邮件状态为"已送达"
- 记录递送统计
- 更新用户活跃度
- 触发后续营销流程

### 拒信处理
- 记录拒信原因
- 检查邮件内容合规性
- 更新发送策略
- 通知管理员

### 退信处理
- 区分硬退信和软退信
- 硬退信：从邮件列表移除
- 软退信：标记重试
- 更新邮箱有效性状态

### 打开/点击处理
- 记录用户行为统计
- 分析用户兴趣
- 更新用户画像
- 触发个性化推荐

### 退订处理
- 立即停止发送邮件
- 更新用户订阅状态
- 记录退订原因
- 发送退订确认

## ⚠️ **注意事项**

1. **重试机制**：腾讯云SES会重试失败的回调，最多3次
2. **响应要求**：必须返回HTTP 200状态码
3. **处理时间**：建议在5秒内完成处理
4. **幂等性**：确保重复回调不会产生副作用
5. **日志记录**：详细记录所有回调事件
6. **监控告警**：设置回调失败告警机制

## 🔧 **扩展功能**

### 数据库设计
```sql
-- 邮件事件表
CREATE TABLE email_events (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    message_id VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    event_type VARCHAR(50) NOT NULL,
    event_data JSON,
    timestamp DATETIME NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 邮件统计表
CREATE TABLE email_statistics (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    email VARCHAR(255) NOT NULL,
    total_sent INT DEFAULT 0,
    total_delivered INT DEFAULT 0,
    total_opened INT DEFAULT 0,
    total_clicked INT DEFAULT 0,
    total_bounced INT DEFAULT 0,
    last_activity DATETIME,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```

### 监控指标
- 回调成功率
- 事件处理延迟
- 各事件类型分布
- 错误率统计

现在您有了一个完整的腾讯云SES邮件验证回调路径设计！