高级功能
邮件追踪 (track)
邮件追踪能够帮助用户收集已发出邮件的「打开数据」,「点击数据」,「退订数据」, 以此来评估邮件发送的效果.
你可以通过【发送设置】-【追踪选项】来配置某个「API_USER」的「打开追踪」,「点击追踪」,「订阅追踪」.
配置追踪域名
使用 ICP 备案通过的域名或其子域名作为追踪域名
配置此域名的 CNAME 记录到 track.sendcloud.org
技术原理
假设客户使用的追踪域名是 track.ifaxin.com,客户需要配置
track.ifaxin.com CNAME track.sendcloud.org
打开追踪
SendCloud 会在客户邮件的末端放置1张1像素的透明图片,一般情况 MP 的客户端、网页端会自动下载邮件中的图片
当用户打开这封邮件时,用户的邮件客户端会请求下载这张1像素的图片,此时 SendCloud 的 track 服务会记录这次打开操作
点击追踪
假设客户邮件中有一个链接:http://www.ifaxin.com
SendCloud 会修改此链接的 href 值变成:http://track.ifaxin.com?p=xxx
用户点击链接时,链接会通过 CNAME 记录先请求到 track.sendcloud.org 的 track 服务
在完成相应的点击记录之后,track 服务会将此请求 301 到客户的原始链接:http://www.ifaxin.com
取消订阅追踪
SendCloud 会在客户邮件的末端放置1个取消订阅的链接,用户点击此链接会进入取消订阅样式的页面,SendCloud 会记录此用户的邮箱加入到相应的取消订阅列表
取消订阅的链接如图:
地址列表
地址列表是一个方便用户发送邮件的功能. 用户编辑/导入地址列表后, 在请求接口时, 不需要再传输邮件地址, 只需在参数中指定地址列表的「别称地址」即可.
地址列表中可以设置「变量的值」, 用于替换「邮件内容」中的「变量」.
用户可以通过【发送相关】-【地址列表】来创建【地址列表】.
注意:
只有通过 WEBAPI 的方式发送邮件, 才支持使用地址列表. SMTP 接入方式暂不支持.
只有使用 「批量类型」的 API_USER 调用接口, 才支持使用地址列表
只有付费用户才支持使用地址列表
标签 (label)
标签能够帮助用户对邮件进行分类, 适用于 A/B 测试等场景.
给2种风格的邮件赋予不同的标签进行测试发送, 通过标签分别查看2种风格邮件的打开/点击数据
就能知道接收者最喜欢哪种邮件了~
注意: 每封邮件只能使用一个标签
收信路由
如果你能收到你的用户的回信, 那真是一件让人激动的事情, 所以, SendCloud 为你准备了这个贴心的功能.
此功能就是把用户回复到某地址的邮件转发给你设置的邮箱, 或是你设置的某个URL. 你可以接收邮件数据, 再做后续处理.
当然, 直接发给这个地址的邮件也会被转发.
用户可以通过某个域名配置里面的【收信配置】-【添加收信路由】来创建收信路由.
订阅关系
订阅关系的作用是帮助用户创建, 维护和用户的订阅关系, 帮助用户快速搭建自己的邮件订阅系统.
SendCloud 和 ESP 都在推进建立用户和用户订阅关系, 也会大力支持这种存在订阅关系的邮件发送 ( 比如 QQ邮件列表 ).
客户在 SendCloud 中配置生成一个「订阅关系」:
客户将生成的 JS 代码放置在自己的网站中
用户访问客户的网站时, 输入邮箱地址, 订阅某条信息
用户的邮箱地址自动加入客户的某个「地址列表」.
用户收到确认邮件, 确认订阅操作.
这样, 用户就完成了和客户网站的订阅关系.
此功能依赖于「地址列表」, 客户在配置订阅关系时需要将此订阅关系绑定到某个「地址列表」.
取消订阅样式
在开启「订阅追踪」后, 系统会在邮件中默认自动加上 取消订阅 的退订链接, 供收件人退订此类邮件.
下面是系统默认的取消订阅样式:
你可以自行定义取消订阅的样式, 只要在 href 中插入 SendCloud 内部变量 %%user_defined_unsubscribe_link%% 即可. 示例如下:
使用默认的取消订阅样式, 邮件无需特别处理, 内容如下:
亲爱的%name%:
您好! 您本月在爱发信的消费金额为: %money% 元.
邮件内容效果截图如下:
使用自定义的取消订阅样式, 邮件内容如下:
亲爱的%name%:
您好! 您本月在爱发信的消费金额为: %money% 元.
邮件内容效果截图如下:
WebHook
用户将邮件请求发送给 SendCloud 之后, SendCloud 会把「请求结果」同步返回给用户, 而邮件的「发送结果」和「其他事件结果」是通过 WebHook 异步返回给用户的.
WebHook 机制:
SendCloud 为客户提供了一些邮件事件, 客户可以选择关注某些事件
当某事件发生, 就会触发 SendCloud 向客户设置的 URL 发送数据 ( POST )
SendCloud推送的数据类型:"Content-Type: application/x-www-form-urlencoded"
客户收到数据, 解析出事件和数据, 你需要在 3s 内返回HTTP Status Code 200, 否则, SendCloud 将会重发该条消息.点此查看WEBHOOK解析示例
目前 SendCloud 支持的邮件事件如下:
事件
触发条件
请求(request)
邮件请求成功
发送(deliver)
邮件发送成功
打开(open)
用户打开邮件
点击(click)
用户点击链接
取消订阅(unsubscribe)
用户取消订阅邮件
举报(report_spam)
用户举报邮件
无效邮件(invalid)
邮件未发送成功
软退信(soft_bounce)
接收方拒收该邮件
转信(route)
转信/收信路由
使用方法:
用户自行编写 HTTP 服务, 使之能够处理相应的事件, 解析相关数据, 并开放出相应 URL
用户在 SendCloud 的 【邮件】- 【发送设置】-【WebHook】 中选择关注的事件, 配置接收数据的 URL
注意: 我们会对用户提供的 URL 做检测. 需要此 HTTP 服务能够正确响应 get | post 请求, 并且保证返回的 HTTP 状态码 为 200
签名验证
为了确保消息的来源身份是 SendCloud, 你可以选择对 POST 数据的来源进行安全认证. ( 不验证, 直接解析 POST 的数据也可以 ).
安全认证的方法如下:
通过【发送设置】-【WebHook】获取 APP KEY
解析出 POST 数据中的 token, timestamp 和 signature
使用 APP KEY, token 和 timestamp 生成签名 signature, 与 POST 数据中的 signature 进行校验 ( 签名算法: SHA256)
python 代码示例
import hashlib, hmac
def verify(appkey, token, timestamp, signature):
return signature == hmac.new(
key=appkey,
msg='{}{}'.format(timestamp, token),
digestmod=hashlib.sha256).hexdigest()
Java 代码示例 (依赖 apache codec)
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Hex;
public boolean verify(String appkey, String token, long timestamp,
String signature) throws NoSuchAlgorithmException, InvalidKeyException {
Mac sha256HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(appkey.getBytes(),"HmacSHA256");
sha256HMAC.init(secretKey);
StringBuffer buf = new StringBuffer();
buf.append(timestamp).append(token);
String signatureCal = new String(Hex.encodeHex(sha256HMAC.doFinal(buf
.toString().getBytes())));
return signatureCal.equals(signature);
}
php 代码示例
function verify($appkey,$token,$timestamp,$signature){
$hash="sha256";
$result=hash_hmac($hash,$timestamp.$token,$appkey);
return strcmp($result,$signature)==0?1:0;
}
重试机制
如果遇到 URL 访问错误或超时, SendCloud 最多会重试 6 次. 每次重试的时间间隔最快为 3min, 10min, 30min, 1h, 6h, 12h, 24h. 即在消息丢失前, 你有足够的时间来修复 URL.
如果超过重试次数,SendCloud 将会把消息丢弃.
每次事件处理, 数据解析, 你需要在 3s 内返回状态码 200, 否则, SendCloud 将会重发该条消息。
事件说明
目前 WebHook 支持的事件类型包括: 请求, 发送, 打开, 点击, 取消订阅, 举报, 无效邮件.
请求事件 ( request )
参数说明
参数
类型
说明
event
string
事件类型:"request"
message
string
消息内容
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
messageId
string
messageId
apiUser
string
API_USER
category
string
同 apiUser
recipientArray
list
请求的收件人
emailIds
list
emailId 数组
labelId
int
自定义的标签ID
recipientSize
int
本次请求的个数
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
发送 ( deliver )
参数说明
参数
类型
说明
event
string
事件类型:"deliver"
message
string
消息内容
apiUser
string
API_USER
category
string
同 apiUser
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
labelId
int
自定义的标签ID
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
打开 ( open )
参数说明
参数
类型
说明
event
string
事件类型:"open"
message
string
消息内容
apiUser
string
API_USER
category
string
同 apiUser
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
labelId
int
自定义的标签ID
ip
string
打开的Ip地址
explorerName
string
浏览器名称
explorerVer
string
浏览器版本
oSName
string
操作系统名称
oSVer
string
操作系统版本
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
点击 ( click )
参数说明
参数
类型
说明
event
string
事件类型:"click"
message
string
消息内容
apiUser
string
API_USER
category
string
同 apiUser
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
labelId
int
自定义的标签ID
url
string
被点击的链接
ip
string
点击的Ip地址
explorerName
string
浏览器名称
explorerVer
string
浏览器版本
oSName
string
操作系统名称
oSVer
string
操作系统版本
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
取消订阅 ( unsubscribe )
参数说明
参数
类型
说明
event
string
事件类型:"unsubscribe"
message
string
消息内容
apiUser
string
API_USER
category
string
同 apiUser
labelId
int
自定义的标签ID
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
ip
string
Ip地址
explorerName
string
浏览器名称
explorerVer
string
浏览器版本
oSName
string
操作系统名称
oSVer
string
操作系统版本
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
垃圾举报 ( report_spam )
参数说明
参数
类型
说明
event
string
事件类型:"report_spam"
message
string
消息内容
apiUser
string
API_USER
category
string
同 apiUser
labelId
int
自定义的标签ID
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
无效邮件 ( invalid )
参数说明
参数
类型
说明
event
string
事件类型:"invalid"
message
string
消息内容
apiUser
string
API_USER
category
string
同 apiUser
labelId
int
自定义的标签ID
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
subStatDesc
string
无效子类描述
subStat
Integer
无效子类
无效子类返回码和描述:
subStat
subStatDesc
401
在SendCloud黑名单中
402
取消订阅
403
服务器不可达
404
地址格式错误
405
IP、域名被拒
406
地址不存在
407
垃圾邮件
408
发件人/收件人被拒
409
其他
软退信 ( soft_bounce )
参数说明
参数
类型
说明
event
string
事件类型:"soft_bounce"
apiUser
string
API_USER
category
string
同 apiUser
labelId
int
自定义的标签ID
maillistTaskId
long
如果使用地址列表发送,将产生任务id
mail_list_task_id
long
同 maillistTaskId
emailId
string
每封email的唯一ID
recipient
string
收信人
timestamp
long
时间戳
token
string
随机产生的长度为50的字符串
signature
string
签名字符串
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
subStatDesc
string
软退信子类描述
subStat
Integer
软退信子类
cause
string
软退信原因
软退信子类返回码和描述:
subStat
subStatDesc
503
服务不可达
505
ip或域名被拒
506
邮箱地址不存在
507
垃圾邮件
508
发件人/收件人被拒
509
其他
转信 ( route )
参数说明
参数
类型
说明
event
string
事件类型:"route"
from
string
发件人地址
fromname
string
发件人名称
headers
string
邮件头部信息. JSON 格式
html
string
转信邮件 html 格式的内容
message
string
消息内容 "mx route"
raw_message
string
转信邮件的邮件原文,包括附件信息,需要用户解析
signature
string
签名字符串
subject
string
标题
text
string
转信邮件文本格式的内容
timestamp
long
时间戳
to
string
收件人地址
token
string
随机产生的长度为50的字符串
toname
string
收件人名称
userHeaders
string
用户自定义, 并且以"SC-Custom-"开头的头部信息
reference
string
邮件回复对应到emailId
注意: raw_message中的附件数据编码为base64
POST 数据示例
maillistTaskId=-1&signature=eb6484eb14a429f7ea367647ffc9bc617ac8ce858afa2705d247f21177760ded&mail_list_task_id=-1&emailId=1576829271482_66557_24087_8851.sc-10_9_13_218-inbound0%24allsa%40sendcloud.cn&message=Successfully+delivered&apiUser=51eat_trigger&token=34szcNvC15W8wxLr1dONdBEuCfn4n4DpxHooDAkGMJf5pG2zVP&userHeaders=%7B%7D&labelId=0&recipient=allsa%40sendcloud.cn&event=deliver&category=51eat_trigger×tamp=1576829272783