邮件代理中的网络挂钩

什么是网络挂钩？

网络挂钩是由事件触发的用户定义的 HTTP 回调。在 ZeptoMail 中，网络挂钩可用于根据已发送电子邮件的收件人活动向您的应用程序转发数据。网络挂钩转发其收件人数据的事件包括电子邮件的打开、点击和退回。网络挂钩会立即将数据转发到配置的 URL，而您的应用程序会收到即时通知。

发生特定事件时，将触发网络挂钩。即，对开发人员配置为接收网络挂钩的 URL（或 URI）发出 HTTP POST 请求。电子邮件网络挂钩最有用的功能是在发生任意此类事件时获取用户详细信息。应用程序开发人员必须在 ZeptoMail 中配置网络挂钩 URL，才能在发生这些事件时接收收件人详细信息。您可以在邮件代理中预览网络挂钩数据并对其进行测试。

网络挂钩的类型

我们可以将网络挂钩分为 3 种类型：

退回网络挂钩
电子邮件打开网络挂钩
链接点击网络挂钩

退回网络挂钩

通过使用退回网络挂钩，当您的事务性电子邮件退回时，您可以接收收件人详细信息。可在此处查看 ZeptoMail 发送的用户详细信息列表。您的电子邮件被退回的原因有多种。例如，如果收件人的邮箱已满，您的电子邮件将暂时退回。此类临时退回称为软退回。如果由于收件人电子邮件地址无效，退回是永久性的，则称为硬退回。

电子邮件打开网络挂钩

电子邮件打开网络挂钩用于在收件人打开电子邮件时检索其详细信息。可在此处查看 ZeptoMail 发送的用户详细信息列表。此事件在收件人首次打开电子邮件时触发。即使收件人多次打开电子邮件，ZeptoMail 也会存储并传输与第一个实例相关的收件人详细信息。

链接点击网络挂钩

有时，您的事务性电子邮件的 HTML 正文中包含可点击的链接。链接点击网络挂钩可以传输点击这些链接的收件人详细信息。可在此处查看 ZeptoMail 发送的用户详细信息列表。ZeptoMail 将在电子邮件中的所有跟踪链接中转发唯一的点击信息。

如果收件人多次点击同一个跟踪链接，ZeptoMail 只会记录唯一的点击并通过网络挂钩 URL 将其转发到应用程序。

配置网络挂钩 URL

从左侧面板中，选择邮件代理，然后选择要为其添加网络挂钩的邮件代理。
导航至网络挂钩选项卡。
单击配置网络挂钩。

配置网络挂钩 URL

将出现添加网络挂钩框。您可以在此处添加网络挂钩并进行测试。
输入网络挂钩 URL、描述并选择您希望网络挂钩将此数据转发到应用程序的通知（包括软退回、硬退回、打开和点击）。

添加网络挂钩

填写所需的详细信息后，单击保存。
网络挂钩配置成功。
如果要向 ZeptoMail 邮件代理添加更多的网络挂钩，请单击右侧的添加网络挂钩按钮。

向您的邮件代理添加更多网络挂钩

您可以按照相同的步骤添加多个网络挂钩。

编辑您的网络挂钩 URL

从左侧面板中，选择邮件代理，然后选择要为其添加网络挂钩的邮件代理。
导航至网络挂钩选项卡。此处将列出为您的邮件代理配置的网络挂钩列表。
将光标悬停在网络挂钩上，以查看“编辑网络挂钩”图标。
单击编辑网络挂钩以打开添加网络挂钩框。

编辑您的网络挂钩 URL

您可以编辑网络挂钩 URL、描述，并从这些通知中选择/取消选择 - 软退回、硬退回、打开和点击。

编辑网络挂钩 URL 和描述

单击保存以将更改应用到您的网络挂钩 URL。

测试您的网络挂钩 URL

您可以在创建新的网络挂钩 URL 时测试网络挂钩 URL，或者针对现有网络挂钩 URL 进行测试。您可以针对软退回、硬退回、打开和点击单独测试网络挂钩 URL。

从左侧面板中，选择邮件代理，然后选择要将网络挂钩添加到的邮件代理。
导航至网络挂钩选项卡。您将看到“网络挂钩”页面，您可以在其中查看该邮件代理的网络挂钩列表。
如果要添加新的网络挂钩，请单击添加网络挂钩。如果是现有的网络挂钩 URL，请单击右侧的编辑图标。
现在，通过单击下拉列表，从要测试的“软退回”、“硬退回”、“打开”和“点击”中选择通知。

测试您的网络挂钩 URL

单击发送测试并检查数据是否成功接收。

验证您的网络挂钩 URL

网络挂钩 URL 应公开，以便 ZeptoMail 发送数据。由于其公开的特性，该 URL 容易遭受威胁。黑客可能通过向公共网络挂钩 URL 发布不相关的信息来操纵 URL 数据。

为了保护网络挂钩 URL，ZeptoMail 提供了一个身份验证密钥。身份验证可以保护您的网络挂钩 URL 免于不相关的点击。您可以添加身份验证密钥，将其作为发送到网络挂钩 URL 的数据的一部分。然后，您的应用程序可以使用此身份验证密钥来验证传入的网络挂钩数据。

从左侧面板中，选择邮件代理，然后选择要将网络挂钩添加到的邮件代理。
导航至网络挂钩选项卡。您将看到“网络挂钩”页面，您可以在其中查看该邮件代理的网络挂钩列表。
单击右上角的身份验证密钥。

验证您的网络挂钩 URL

输入身份验证密钥并单击设置。
使用身份验证密钥验证发送到应用程序的网络挂钩数据。

删除您的网络挂钩 URL

您可以删除网络挂钩 URL，但您必须再次添加它才能重新使用它。

从左侧面板中，选择邮件代理，然后选择要将网络挂钩添加到的邮件代理。
导航至网络挂钩选项卡。您将看到“网络挂钩”页面，您可以在其中查看该邮件代理的网络挂钩列表。
找到要删除的网络挂钩并将光标悬停在其上方。
单击右侧角落处的删除图标。

删除您的网络挂钩 URL

单击“确定”确认删除网络挂钩。

标准报告数据

退回网络挂钩

event_name - 事件的类型。这将是硬退回或软退回
event_message - 有关事件的详细信息
- email_info - 这将提供退回电子邮件的详细信息，例如：
  - email_reference - 用于跟踪电子邮件
  - is_smtp_trigger - true 表示使用 SMTP 触发网络挂钩
  - subject - 退回电子邮件的主题
  - bounce_address - 邮件代理中配置的退回电子邮件地址和名称
  - from - 发件人电子邮件地址详细信息
    - address - 发件人电子邮件地址
    - name - 发件人名称
  - to - 要向其发送退回详细信息的电子邮件地址。您可以在此处添加任意数量的“收件人”地址
    - email_address - 用于添加多个电子邮件地址的 JSON 数组
      - address - 将退回详细信息发送到的电子邮件地址
  - processed_time - 发送电子邮件时的时间戳
  - object - event_message 数据针对的是对象电子邮件
- event_data - 此字段提供退回原因、退回时间和诊断消息
  - details - 退回的详细信息，如 reason、time 和 diagnostic_message
    - reason - 退回原因
    - time - 退回时间
    - diagnostic_message - 帮助排除故障
  - object - event_data 针对的是对象退回。可以是软退回或硬退回
- request_id - 被退回的电子邮件的唯一标识符
mailagent_key - 邮件代理的唯一标识符
webhook_request_id - 这是特定网络挂钩事务的唯一 ID。

电子邮件打开网络挂钩

event_name - 事件的类型。此处跟踪的事件是电子邮件打开。
event_message - 有关事件的详细信息
- email_info - 这提供了打开的电子邮件的详细信息，例如：
  - email_reference - 用于跟踪电子邮件
  - is_smtp_trigger - true 表示使用 SMTP 触发网络挂钩
  - subject - 打开的电子邮件的主题
  - bounce_address - 配置的退回地址
  - from - 发件人电子邮件地址详细信息
    - address - 发件人电子邮件地址
    - name - 发件人名称
  - to - 要向其发送退回详细信息的电子邮件地址。您可以在此处添加任意数量的“收件人”地址
    - email_address - 用于添加多个电子邮件地址的 JSON 数组
      - address - 将退回详细信息发送到的电子邮件地址
  - processed_time - 发送电子邮件时的时间戳
  - object - event_message 数据针对的是对象电子邮件
- event_data - 此字段提供有关事件的详细信息
  - details - 详细信息，例如 email_client、modified_time、ip_location_info、browser、operating_system、time 和 device
    - email_client - 收件人电子邮件客户端的详细信息
      - name - 收件人电子邮件客户端的名称
      - version - 收件人电子邮件客户端的版本
    - modified_time - 打开事件的发生时间
    - ip_location_info - 收件人 IP 位置的详细信息
      - zipcode - 收件人的邮政编码
      - country_code - 收件人的 country_code
      - city - 事件发生时收件人所在的城市
      - latitude - 事件发生时收件人所在的纬度
      - country_name - 事件发生时收件人所在的国家/地区
      - ip_address - 收件人在打开电子邮件时使用的 IP 地址
      - time_zone - 收件人所在时区
      - region - 收件人所在区域
      - longitude - 收件人所在的经度
    - browser - 收件人用于打开电子邮件的浏览器详细信息
      - name - 浏览器名称
      - version - 浏览器版本
    - operating_system - 收件人使用的操作系统的详细信息
      - name - 收件人操作系统的名称
      - version - 收件人操作系统的版本
    - time - 事件发生的时间
    - device - 收件人设备的详细信息
      - name - 收件人设备的名称
  - object - event_data 针对的是对象 email_open
- request_id - 打开的电子邮件的唯一标识符
mailagent_key - 邮件代理的唯一标识符
webhook_request_id - 这是特定网络挂钩事务的唯一 ID

链接点击网络挂钩

event_name - 事件的类型。此处跟踪的事件是电子邮件点击。
event_message - 有关事件的详细信息
- email_info - 这提供了点击的电子邮件的详细信息，例如：
  - email_reference - 用于跟踪电子邮件
  - is_smtp_trigger - true 表示使用 SMTP 触发网络挂钩
  - subject - 点击的电子邮件的主题
  - bounce_address - 配置的退回地址
  - from - 发件人电子邮件地址详细信息
    - address - 发件人电子邮件地址
    - name - 发件人名称
  - to - 要向其发送退回详细信息的电子邮件地址。您可以在此处添加任意数量的“收件人”地址
    - email_address - 用于添加多个电子邮件地址的 JSON 数组
      - address - 将退回详细信息发送到的电子邮件地址
  - processed_time - 发送电子邮件时的时间戳
  - object - event_message 数据针对的是对象电子邮件
- event_data - 此字段提供有关事件的详细信息
  - details - 详细信息，例如 email_client、modified_time、ip_location_info、browser、operating_system、time 和 device
    - email_client - 收件人电子邮件客户端的详细信息
      - name - 收件人电子邮件客户端的名称
      - version - 收件人电子邮件客户端的版本
    - modified_time - 打开事件的发生时间
    - ip_location_info - 收件人 IP 位置的详细信息
      - zipcode - 收件人的邮政编码
      - country_code - 收件人的 country_code
      - city - 事件发生时收件人所在的城市
      - latitude - 事件发生时收件人所在的纬度
      - country_name - 事件发生时收件人所在的城市
      - ip_address - 收件人在打开电子邮件时使用的 IP 地址
      - time_zone - 收件人所在时区
      - region - 收件人所在区域
      - longitude - 收件人所在的经度
    - browser - 收件人用于打开电子邮件的浏览器详细信息
      - name - 浏览器名称
      - version - 收件人操作系统的版本
    - operating_system - 收件人使用的操作系统的详细信息
      - name - 收件人操作系统的名称
      - version - 收件人操作系统的版本
    - time - 事件发生的时间
    - device - 收件人设备的详细信息
      - name - 收件人设备的名称
  - object - event_data 针对的是对象 email_link_click
- request_id - 被点击的电子邮件的唯一标识符
mailagent_key - 邮件代理的唯一标识符。
webhook_request_id - 这是特定网络挂钩事务的唯一 ID。

保护网络挂钩

建议保护您的网络挂钩，因为它可以帮助您确定请求是否确实来自 ZeptoMail。为了让您能够验证网络挂钩，ZeptoMail 会在其所有网络挂钩请求中添加签名。这为您的网络挂钩增加了额外一层的安全保护。

验证网络挂钩请求

每个网络挂钩请求的请求标头中都包含一个生成方签名，用于验证请求是否由 ZeptoMail 生成。生成方签名包含 3 个部分 - 时间戳、签名和签名算法。

ts - 时间戳是从 ZeptoMail 服务器向用户配置的 URL 发起网络挂钩请求的时间
s - 签名是使用您在邮件代理中添加的身份验证密钥对网络挂钩事件通知进行编码时生成的 MAC 消息
s-algorithm - 签名算法是标准的 HMAC SHA256 算法，用于对网络挂钩请求的有效负载进行签名

示例生成方签名格式：ts=1596109465823;s=dN0yVozgabP5NPlxMDfP1r5u65bVO9kTGEZMIQlqI2o%3D;s-algorithm=HmacSHA256

您可以在应用程序中使用以下示例代码来验证网络挂钩请求。该算法将返回一个布尔值 True 或 False。True 表示网络挂钩请求由 ZeptoMail 生成，而 False 表示网络挂钩请求并非来自 ZeptoMail。

示例代码：

import javax.crypto.Mac;

import javax.crypto.spec.SecretKeySpec;

import javax.servlet.http.HttpServletRequest;

import java.io.BufferedReader;

import java.net.URLDecoder;

import java.security.MessageDigest;

import java.time.Duration;

import org.apache.commons.codec.Charsets;

import org.apache.commons.codec.binary.Base64;

import org.json.JSONObject;

public class WebhookRequestValidator {

/**
*
* @param request
* @param acceptableDuration -从 ZeptoMail 服务器发起请求到配置的网络挂钩 URL 目标的时间中，请求可能遭遇的最大真实延迟。
* @param secretKey - 在 ZeptoMail 门户中配置的密钥/验证密钥
* @throws 异常
**/
public static void authenticateWebhookContent(HttpServletRequest request, Duration acceptableDuration, byte[] secretKey)

throws Exception {

String producerSignature = request.getHeader("producer-signature");

String psDecoded = URLDecoder.decode(producerSignature, "UTF-8");

String sign[] = psDecoded.split(";");

JSONObject signJSON = new JSONObject();

for (int i = 0; i < sign.length; i++) {

String field = sign[i];

String fieldArr[] = field.split("=", 2);

signJSON.put(fieldArr[0], fieldArr[1]);

}

long timeSent = Long.valueOf(signJSON.getString("ts"));

long diff = System.currentTimeMillis() - timeSent;

long acceptableLimit = acceptableDuration.toMillis();

if (diff <= acceptableLimit) {

String signatureAlgorithm = signJSON.getString("s-algorithm");

String signatureReceived = signJSON.getString("s");

StringBuffer requestBody = new StringBuffer();

String value = null;

BufferedReader reader = request.getReader();

while ((value = reader.readLine()) != null) {

requestBody.append(value);

}

String data = requestBody.toString();

String dataDecoded = URLDecoder.decode(data, "UTF-8");

String arr[] = dataDecoded.split("=", 2);

String dataValue = arr[1];

String constructedSignature = getSignature(dataValue, secretKey, signatureAlgorithm);

byte decode1[] = Base64.decodeBase64(signatureReceived);

byte decode2[] = Base64.decodeBase64(constructedSignature);

if (!MessageDigest.isEqual(decode1, decode2)) {

throw new Exception("Message digest isn't equal");

}

private static String getSignature(String data, byte[] secretKey, String signatureAlgorithm) throws Exception {

SecretKeySpec signingKey = new SecretKeySpec(secretKey, signatureAlgorithm);

Mac mac = Mac.getInstance(signatureAlgorithm);

mac.init(signingKey);

byte[] rawHmac = mac.doFinal(data.getBytes(Charsets.UTF_8));

String result = Base64.encodeBase64String(rawHmac);

return result;

}

;i++)>

注意：

在您开始之前，请务必了解 ZeptoMail 用于发送诸如欢迎邮件、密码重置电子邮件、OTP 等事务性电子邮件。我们不支持发送批量电子邮件或促销电子邮件（例如，时事通讯或营销活动电子邮件）。如果您正在寻找批量电子邮件提供商，请了解一下 Zoho Campaigns。

邮件代理中的网络挂钩

目录

网络挂钩的类型

退回网络挂钩

电子邮件打开网络挂钩

链接点击网络挂钩

配置网络挂钩 URL

编辑您的网络挂钩 URL

测试您的网络挂钩 URL

验证您的网络挂钩 URL

删除您的网络挂钩 URL

标准报告数据

退回网络挂钩

电子邮件打开网络挂钩

链接点击网络挂钩

保护网络挂钩

验证网络挂钩请求