> ## Documentation Index > Fetch the complete documentation index at: https://developer.effilink.co/llms.txt > Use this file to discover all available pages before exploring further. # Webhook 事件 > EffiLink 全部 8 种 Webhook 事件类型（Dropped、Bounced、Delivered、Opened、Clicked、Unsubscribed、SpamReport 和 TaskStatus）的完整字段参考。 本页面记录 EffiLink 可以向 Webhook 端点投递的每种事件类型，包括触发时机的描述以及推送中的完整字段表。有关配置说明和一般行为，请参见[Webhook 配置](/zh/docs/webhooks)。 *** ## 批量投递 EffiLink 以批量方式投递 Webhook 事件。每次 HTTP POST 到您的端点都包含事件对象的 JSON **数组**，单次推送最多 **1,000 个事件**。同一次推送可能包含不同类型的事件，因此处理器应根据数组中每个对象的 `EventCode` 字段进行分支处理。 ```json theme={null} [ { "EventCode": "Delivered", ... }, { "EventCode": "Opened", ... }, { "EventCode": "Clicked", ... } ] ``` *** ## 通用字段 以下字段在大多数或全部事件类型中都会出现。个别事件可能包含额外字段，见下方各自的章节。 | 字段 | 类型 | 说明 | | --------------------- | -------- | ----------------------------------------- | | `EventCode` | string | 标识事件类型（例如 `"Delivered"`、`"Opened"`）。 | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动分类（例如 `"Transactional"`、`"Marketing"`）。 | | `SentMailListName` | string | 邮件发送的目标联系人列表名。 | | `TriggeredDateTimeV2` | datetime | 事件发生时的 UTC 时间戳。 | | `UniqueMsgID` | string | 单条消息的唯一标识。与 `EventCode` 组合可作为幂等处理的复合键。 | | `Guid` | string | 任务标识。 | | `MailName` | string | 邮件任务的名称。 | *** ## 事件类型 **EventCode：** `Dropped` 当 EffiLink 因收件人地址被抑制过滤器标记而阻止邮件发送时触发。该邮件不会提交给邮件服务器。 **触发时机：** 发送前，联系人记录上的 `properties.email_bounced_flag` 非零时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | -------------- | | `EventCode` | string | `"Dropped"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `Reason` | int | 抑制原因码，见下表。 | | `SenderEmail` | string | 本次活动使用的发件地址。 | | `SentMailListName` | string | 目标联系人列表名。 | | `TriggeredDateTimeV2` | datetime | 丢弃事件的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | **原因码** | 值 | 含义 | | ----- | ------------------ | | `110` | 硬退信过滤：该地址此前发生硬退信。 | | `111` | 退订过滤：联系人已退订。 | | `112` | 投诉过滤：联系人此前举报为垃圾邮件。 | | `210` | 其他过滤（管理员或系统抑制）。 | **EventCode：** `Bounced` 当邮件已提交至收件方邮件服务器但投递失败时触发。EffiLink 区分永久失败（硬退信）与临时失败（软退信）。 **触发时机：** 提交至收件方邮件服务器后，收到失败响应时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | ----------------------------- | | `EventCode` | string | `"Bounced"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `Reason` | int | 退信类型码，见下表。 | | `SenderEmail` | string | 发件地址。 | | `SentMailListName` | string | 目标联系人列表名。 | | `SubmitDateTimeV2` | datetime | 邮件提交时的 UTC 时间戳。 | | `TriggeredDateTimeV2` | datetime | 记录退信时的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `FailedCause` | string | 来自收件方服务器的退信诊断信息，采用 Base64 编码。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | **原因码** | 值 | 含义 | | ----- | ------------------------------------------------------- | | `100` | 硬退信：永久投递失败（例如地址不存在）。联系人的 `email_bounced_flag` 会被设为 `1`。 | | `101` | 软退信：临时投递失败（例如邮箱已满、服务器不可用）。 | 对 `FailedCause` 进行 Base64 解码可读取原始 SMTP 错误消息，有助于诊断异常退信模式。 **EventCode：** `Delivered` 当收件方邮件服务器接受邮件时触发。注意“Delivered”意味着服务器已接受消息，并不保证邮件到达收件箱（仍可能被收件人邮件客户端过滤到垃圾箱）。 **触发时机：** 收到收件方邮件服务器返回的 `250 OK`（或等效）成功响应时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | ----------------- | | `EventCode` | string | `"Delivered"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `SenderEmail` | string | 发件地址。 | | `SentMailListName` | string | 目标联系人列表名。 | | `SubmitDateTimeV2` | datetime | 邮件提交时的 UTC 时间戳。 | | `TriggeredDateTimeV2` | datetime | 确认投递的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `ReceiveServer` | string | 接受消息的收件方邮件服务器主机名。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | **EventCode：** `Opened` 每次收件人打开邮件时触发。同一收件人多次打开会生成多次 `Opened` 事件。打开跟踪通过嵌入在邮件正文中的 1×1 隐藏像素图片实现。 **触发时机：** 收件人邮件客户端加载跟踪像素时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | --------------------------------------------- | | `EventCode` | string | `"Opened"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `SentMailListName` | string | 目标联系人列表名。 | | `SubmitDateTimeV2` | datetime | 邮件提交时的 UTC 时间戳。 | | `DeliveredTimeV2` | datetime | 邮件投递时的 UTC 时间戳。 | | `TriggeredDateTimeV2` | datetime | 本次打开事件的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `IP` | string | 邮件被打开时的 IP 地址。 | | `Platform` | string | 操作系统或设备平台（例如 `"iOS"`、`"Windows"`）。 | | `BrowserType` | string | 打开邮件所用的邮件客户端或浏览器（例如 `"Gmail"`、`"AppleMail"`）。 | | `UA` | string | 打开请求的完整 User-Agent 字符串。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | 打开跟踪依赖收件人邮件客户端加载图片。部分客户端默认屏蔽图片加载，可能导致打开事件低估。Apple Mail Privacy Protection（MPP）也可能导致打开事件虚高或延迟。 **EventCode：** `Clicked` 每次收件人点击邮件中被跟踪的链接时触发。每次点击生成一个事件，收件人点击三个不同链接会产生三个 `Clicked` 事件。触发前提是您在 EffiLink 账户或活动中启用了点击跟踪。 **触发时机：** 收件人点击被跟踪链接并通过 EffiLink 点击跟踪服务重定向时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | ----------------------- | | `EventCode` | string | `"Clicked"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `SentMailListName` | string | 目标联系人列表名。 | | `SubmitDateTimeV2` | datetime | 邮件提交时的 UTC 时间戳。 | | `DeliveredTimeV2` | datetime | 邮件投递时的 UTC 时间戳。 | | `TriggeredDateTimeV2` | datetime | 本次点击事件的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `IP` | string | 点击链接时的 IP 地址。 | | `Platform` | string | 操作系统或设备平台。 | | `BrowserType` | string | 打开链接所使用的浏览器。 | | `UA` | string | 点击请求的完整 User-Agent 字符串。 | | `Link` | string | 被点击的目标 URL。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | **EventCode：** `Unsubscribed` 当收件人点击邮件中的退订链接时触发。EffiLink 会自动将该联系人的 `email_bounced_flag` 更新为 `2`（退订过滤），阻止后续发送。 **触发时机：** 退订动作被确认时（根据您的设置，可能是一键退订或经确认页面）。 | 字段 | 类型 | 说明 | | --------------------- | -------- | ---------------- | | `EventCode` | string | `"Unsubscribed"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `SentMailListName` | string | 目标联系人列表名。 | | `TriggeredDateTimeV2` | datetime | 退订事件的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | | `Reason` | string | 若已收集，收件人提供的退订原因。 | **EventCode：** `SpamReport` 当收件人在邮件客户端点击“举报垃圾邮件”或“标记为垃圾”时触发（反馈回路事件）。EffiLink 会自动将该联系人的 `email_bounced_flag` 更新为 `3`（投诉过滤）。 **触发时机：** 收到来自收件人邮件服务商的反馈回路投诉时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | -------------- | | `EventCode` | string | `"SpamReport"` | | `Email` | string | 收件人邮箱地址。 | | `EventType` | string | 活动类型。 | | `SenderEmail` | string | 发件地址。 | | `SentMailListName` | string | 目标联系人列表名。 | | `TriggeredDateTimeV2` | datetime | 投诉事件的 UTC 时间戳。 | | `UniqueMsgID` | string | 消息唯一标识。 | | `Guid` | string | 活动标识。 | | `MailName` | string | 活动名称。 | 较高的垃圾邮件投诉率会损害发件人声誉。请密切关注 `SpamReport` 事件，调查产生投诉的活动内容和发送实践。大多数邮件服务商认为超过 0.1% 的投诉率就存在问题。 **EventCode：** `TaskStatus` 当营销任务状态变化时触发。可用于触发下游工作流，例如在发送完成时启动一个活动后报表任务。 **触发时机：** 活动转变为 `Created`（任务已排程或入队）或 `Completed`（所有发送已尝试）时。 | 字段 | 类型 | 说明 | | --------------------- | -------- | -------------------------------------------------------------- | | `EventCode` | string | `"TaskStatus"` | | `StatusCode` | string | `"Created"` 表示任务已创建/入队；`"Sending"`（发送中）；`"Completed"` 表示任务已完成。 | | `TriggeredDateTimeV2` | datetime | 状态变化的 UTC 时间戳。 | | `MailName` | string | 活动名称。 | | `Guid` | string | 活动标识。 | | `Creator` | string | 创建该营销任务的用户或 API 密钥。 | | `LanguageCode` | string | 活动关联的语言/区域代码。 | | `MarketName` | string | 活动的市场或区域名称。 | | `SubscriptName` | string | 任务所属的订阅或套餐名称。 | | `ProjectCode` | string | 项目或子账户代码（如适用）。 | | `Description` | string | 可读的状态描述或备注。 | *** ## 延伸阅读 * [Webhooks 概览与配置](/zh/docs/webhooks)：配置端点、安全最佳实践与 API 参考。 * [Webhook 配置 API](/zh/api/webhook-config)：以编程方式获取与保存 Webhook 配置。 * [联系人属性](/zh/docs/contact-properties)：了解 Dropped 事件原因码涉及的 `email_bounced_flag` 值。