Webhook 事件字段详情

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

1. request (请求事件)

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

最终推送字段

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

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "request",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "request",
      "ReceiptCode": "0",
      "ReceiptDesc": "消息内容"
    }
  ]
}

2. deliver (送达事件)

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

最终推送字段

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

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "deliver",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "deliver",
      "ReceiptCode": "0",
      "ReceiptDesc": "消息内容",
      "ClientIp": "192.168.1.1",
      "RecipientEmail": "user@example.com"
    }
  ]
}

3. open (打开事件)

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

最终推送字段

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

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "open",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "open",
      "ReceiptCode": "0",
      "ReceiptDesc": "消息内容",
      "ClientIp": "192.168.1.1",
      "RecipientEmail": "user@example.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	回执描述	✅
ClientIp	点击的IP地址	✅
RecipientEmail	收信人邮箱	✅
ExplorerName	浏览器名称	✅
ExplorerVer	浏览器版本	✅
OSName	操作系统名称	✅
OSVer	操作系统版本	✅
ClickedURL	被点击的链接	✅

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "click",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "click",
      "ReceiptCode": "0",
      "ReceiptDesc": "消息内容",
      "ClientIp": "192.168.1.1",
      "RecipientEmail": "user@example.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	回执描述	✅
ClientIp	IP地址	✅
RecipientEmail	收信人邮箱	✅
ExplorerName	浏览器名称	✅
ExplorerVer	浏览器版本	✅
OSName	操作系统名称	✅
OSVer	操作系统版本	✅
ClickedURL	-	❌

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "unsubscribe",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "unsubscribe",
      "ReceiptCode": "0",
      "ReceiptDesc": "消息内容",
      "ClientIp": "192.168.1.1",
      "RecipientEmail": "user@example.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	回执描述	✅
ClientIp	-	❌
RecipientEmail	收信人邮箱	✅
ExplorerName	-	❌
ExplorerVer	-	❌
OSName	-	❌
OSVer	-	❌
ClickedURL	-	❌

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "report_spam",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "report_spam",
      "ReceiptCode": "0",
      "ReceiptDesc": "消息内容",
      "RecipientEmail": "user@example.com"
    }
  ]
}

7. invalid (无效邮件事件)

Event 类型: invalid
说明: 无效邮件事件，失败事件，包含子状态码

最终推送字段

字段	说明	是否推送
SessionNo	批次ID	✅
MsgId	邮件唯一ID	✅
Event	事件类型，固定值: "invalid"	✅
ReceiptTime	事件时间戳	✅
ReceiptResult	回执状态，格式: "invalid_{SubStat}"，例如: "invalid_405"	✅
ReceiptCode	回执状态码（可能包含子状态码）	✅
ReceiptDesc	无效子类描述	✅
ClientIp	出信IP地址	✅
RecipientEmail	收信人邮箱	✅
ExplorerName	-	❌
ExplorerVer	-	❌
OSName	-	❌
OSVer	-	❌
ClickedURL	-	❌

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "invalid",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "invalid_405",
      "ReceiptCode": "405",
      "ReceiptDesc": "无效子类描述",
      "ClientIp": "192.168.1.1",
      "RecipientEmail": "user@example.com"
    }
  ]
}

8. soft_bounce (软退信事件)

Event 类型: soft_bounce
说明: 软退信事件，失败事件，包含子状态码

最终推送字段

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

最终推送 JSON 示例

{
  "MsgType": 2,
  "Data": [
    {
      "SessionNo": "task_123",
      "MsgId": "email_id_1",
      "Event": "soft_bounce",
      "ReceiptTime": 1234567890,
      "ReceiptResult": "soft_bounce_409",
      "ReceiptCode": "409",
      "ReceiptDesc": "软退信子类描述",
      "ClientIp": "192.168.1.1",
      "RecipientEmail": "user@example.com"
    }
  ]
}

字段推送规则总结

字段	request	deliver	open	click	unsubscribe	report_spam	invalid	soft_bounce
SessionNo	✅	✅	✅	✅	✅	✅	✅	✅
MsgId	✅	✅	✅	✅	✅	✅	✅	✅
Event	✅	✅	✅	✅	✅	✅	✅	✅
ReceiptTime	✅	✅	✅	✅	✅	✅	✅	✅
ReceiptResult	✅	✅	✅	✅	✅	✅	✅	✅
ReceiptCode	✅	✅	✅	✅	✅	✅	✅	✅
ReceiptDesc	✅	✅	✅	✅	✅	✅	✅	✅
ClientIp	❌	✅	✅	✅	✅	❌	✅	✅
RecipientEmail	❌	✅	✅	✅	✅	✅	✅	✅
ExplorerName	❌	❌	✅	✅	✅	❌	❌	❌
ExplorerVer	❌	❌	✅	✅	✅	❌	❌	❌
OSName	❌	❌	✅	✅	✅	❌	❌	❌
OSVer	❌	❌	✅	✅	✅	❌	❌	❌
ClickedURL	❌	❌	❌	✅	❌	❌	❌	❌

图例说明：

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

推送机制说明

推送配置

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

响应格式

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

{
  "code": 0,
  "message": "success"
}

code = 0 表示成功
code != 0 表示失败，会触发重试机制

Webhook 事件字段详情

1. request (请求事件)​

最终推送字段​

最终推送 JSON 示例​

2. deliver (送达事件)​

最终推送字段​

最终推送 JSON 示例​

3. open (打开事件)​

最终推送字段​

最终推送 JSON 示例​

4. click (点击事件)​

最终推送字段​

最终推送 JSON 示例​

5. unsubscribe (取消订阅事件)​

最终推送字段​

最终推送 JSON 示例​

6. report_spam (垃圾举报事件)​

最终推送字段​

最终推送 JSON 示例​

7. invalid (无效邮件事件)​

最终推送字段​

最终推送 JSON 示例​

8. soft_bounce (软退信事件)​

最终推送字段​

最终推送 JSON 示例​

字段推送规则总结​

推送机制说明​

推送配置​

响应格式​

1. request (请求事件)

最终推送字段

最终推送 JSON 示例

2. deliver (送达事件)

最终推送字段

最终推送 JSON 示例

3. open (打开事件)

最终推送字段

最终推送 JSON 示例

4. click (点击事件)

最终推送字段

最终推送 JSON 示例

5. unsubscribe (取消订阅事件)

最终推送字段

最终推送 JSON 示例

6. report_spam (垃圾举报事件)

最终推送字段

最终推送 JSON 示例

7. invalid (无效邮件事件)

最终推送字段

最终推送 JSON 示例

8. soft_bounce (软退信事件)

最终推送字段

最终推送 JSON 示例

字段推送规则总结

推送机制说明

推送配置

响应格式