跳到主要内容

Webhook 事件字段详情

本文档详细说明各 Event 类型的最终推送字段详情。

1. request（请求事件）​

Event 类型：request
说明：请求事件，可能包含多个 emailId，会为每个 emailId 生成一条消息

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："request"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："request"✅
ReceiptCode回执状态码✅
ReceiptDesc回执描述✅
RecipientEmail-✅
Domain发信域名✅
ExplorerName-❌
ExplorerVer-❌
OSName-❌
OSVer-❌
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "request",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "request",
      "ReceiptCode": "request",
      "ReceiptDesc": "Message content",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com"
    }
  ]
}

2. deliver（送达事件）​

Event 类型：deliver
说明：邮件成功送达事件

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："deliver"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："deliver"✅
ReceiptCode回执状态码✅
ReceiptDesc回执描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName-❌
ExplorerVer-❌
OSName-❌
OSVer-❌
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "deliver",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "deliver",
      "ReceiptCode": "0",
      "ReceiptDesc": "Message content",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com"
    }
  ]
}

3. open（打开事件）​

Event 类型：open
说明：邮件被打开事件，包含浏览器和操作系统信息

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："open"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："open"✅
ReceiptCode回执状态码✅
ReceiptDesc回执描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName浏览器名称✅
ExplorerVer浏览器版本✅
OSName操作系统名称✅
OSVer操作系统版本✅
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "open",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "open",
      "ReceiptCode": "0",
      "ReceiptDesc": "Message content",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com",
      "ExplorerName": "Chrome",
      "ExplorerVer": "100.0",
      "OSName": "Windows",
      "OSVer": "10"
    }
  ]
}

4. click（点击事件）​

Event 类型：click
说明：邮件中的链接被点击事件，包含被点击的 URL

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："click"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："click"✅
ReceiptCode回执状态码✅
ReceiptDesc回执描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName浏览器名称✅
ExplorerVer浏览器版本✅
OSName操作系统名称✅
OSVer操作系统版本✅
ClickedURL被点击的链接 URL✅

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "click",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "click",
      "ReceiptCode": "0",
      "ReceiptDesc": "Message content",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com",
      "ExplorerName": "Chrome",
      "ExplorerVer": "100.0",
      "OSName": "Windows",
      "OSVer": "10",
      "ClickedURL": "https://example.com/link"
    }
  ]
}

5. unsubscribe（取消订阅事件）​

Event 类型：unsubscribe
说明：用户取消订阅事件

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："unsubscribe"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："unsubscribe"✅
ReceiptCode回执状态码✅
ReceiptDesc回执描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName浏览器名称✅
ExplorerVer浏览器版本✅
OSName操作系统名称✅
OSVer操作系统版本✅
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "unsubscribe",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "unsubscribe",
      "ReceiptCode": "0",
      "ReceiptDesc": "Message content",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com",
      "ExplorerName": "Chrome",
      "ExplorerVer": "100.0",
      "OSName": "Windows",
      "OSVer": "10"
    }
  ]
}

6. report_spam（垃圾举报事件）​

Event 类型：report_spam
说明：邮件被举报为垃圾邮件事件

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："report_spam"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："report_spam"✅
ReceiptCode回执状态码✅
ReceiptDesc回执描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName-❌
ExplorerVer-❌
OSName-❌
OSVer-❌
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "report_spam",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "report_spam",
      "ReceiptCode": "0",
      "ReceiptDesc": "Message content",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com"
    }
  ]
}

7. bounce（退信事件）​

Event 类型：bounce
说明：退信事件，包括无法成功投递的邮件，通常由收件方邮箱永久性问题或地址无效导致。

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："bounce"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，格式："bounce"，例如："bounce"✅
ReceiptCode回执状态码（可能包含子状态码）✅
ReceiptDesc退信子类描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName-❌
ExplorerVer-❌
OSName-❌
OSVer-❌
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "bounce",
      "ReceiptTime": 1778222019000,
      "ReceiptResult": "bounce",
      "ReceiptCode": "us_bounce_101",
      "ReceiptDesc": "Recipient's address does not exist or has moved",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com"
    }
  ]
}

8. temporary_issue（临时问题事件）​

Event 类型：temporary_issue
说明：软退信事件，包括因临时性原因投递失败的邮件，例如限流或服务器侧拥塞。

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："soft_bounce"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，格式："softbounce{SubStat}"，例如："soft_bounce_409"✅
ReceiptCode回执状态码（可能包含子状态码）✅
ReceiptDesc软退信子类描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName-❌
ExplorerVer-❌
OSName-❌
OSVer-❌
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "soft_bounce",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "soft_bounce_409",
      "ReceiptCode": "409",
      "ReceiptDesc": "Soft bounce sub-category description",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com"
    }
  ]
}

9. blocked（拦截事件）​

Event 类型：blocked
说明：拦截事件，包括因域名声誉、安全策略或 ISP 限制而被拒收的邮件。

最终推送字段​

字段说明是否推送
SessionNo批次 ID✅
MsgId邮件唯一 ID✅
Event事件类型，固定值："blocked"✅
ReceiptTime事件时间戳✅
ReceiptResult回执状态，固定值："blocked"✅
ReceiptCode回执状态码✅
ReceiptDesc拦截原因描述✅
RecipientEmail收信人邮箱✅
Domain发信域名✅
ExplorerName-❌
ExplorerVer-❌
OSName-❌
OSVer-❌
ClickedURL-❌

最终推送 JSON 示例​

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "blocked",
      "ReceiptTime": 1234567890000,
      "ReceiptResult": "blocked",
      "ReceiptCode": "us_block_105",
      "ReceiptDesc": "The recipient address is on the suppression list",
      "RecipientEmail": "user@example.com",
      "Domain": "sender.domain.com"
    }
  ]
}

💡 字段推送规则总结​

字段requestdeliveropenclickunsubscribereport_spambouncetemporary_issueblocked
SessionNo✅✅✅✅✅✅✅✅✅
MsgId✅✅✅✅✅✅✅✅✅
Event✅✅✅✅✅✅✅✅✅
ReceiptTime✅✅✅✅✅✅✅✅✅
ReceiptResult✅✅✅✅✅✅✅✅✅
ReceiptCode✅✅✅✅✅✅✅✅✅
ReceiptDesc✅✅✅✅✅✅✅✅✅
RecipientEmail✅✅✅✅✅✅✅✅✅
Domain✅✅✅✅✅✅✅✅✅
ExplorerName❌❌✅✅✅❌❌❌❌
ExplorerVer❌❌✅✅✅❌❌❌❌
OSName❌❌✅✅✅❌❌❌❌
OSVer❌❌✅✅✅❌❌❌❌
ClickedURL❌❌❌✅❌❌❌❌❌

图例说明：

  • ✅ 表示该字段会推送（字段会出现在 JSON 中）
  • ❌ 表示该字段不会推送（字段值为空字符串，不会出现在 JSON 中）

💡 推送机制说明​

推送配置​

  • 推送方式：HTTP POST
  • Content-Type：application/json
  • 重试机制：每个回调地址最多重试 3 次
  • 批量推送：支持批量推送多条消息
  • 超时设置：可配置请求超时时间（默认 30 秒）

响应格式​

客户端需要返回以下格式的 JSON 响应：

{
  "code": 0,
  "message": "success"
}
  • code = 0 表示成功
  • code != 0 表示失败，会触发重试机制