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	退订	收件人选择退订邮件

📝 回调数据格式

基础数据结构

{
  "eventType": "delivery",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

递送成功事件

{
  "eventType": "delivery",
  "messageId": "0000014a-f4d4-4f4f-8f4f-4f4f4f4f4f4f-000000",
  "email": "user@example.com",
  "timestamp": "2024-01-01T12:00:00.000Z"
}

拒信事件

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

退信事件

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

打开事件

{
  "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"
}

点击事件

{
  "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"
}

退订事件

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

🔒 安全验证

请求头验证

X-Tencent-Token: your-token
X-Tencent-Timestamp: 1640995200
X-Tencent-Signature: calculated-signature

签名验证流程

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

🚀 ngrok测试配置

1️⃣ 启动ngrok

# 穿透后端端口8080
ngrok http 8080

2️⃣ 获取公网地址

Forwarding    https://abc123.ngrok.io -> http://localhost:8080

3️⃣ 配置回调地址

https://abc123.ngrok.io/api/tencent/ses/webhook

4️⃣ 测试回调

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. 监控告警：设置回调失败告警机制

🔧 扩展功能

数据库设计

-- 邮件事件表
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邮件验证回调路径设计！