Webhook接口说明
如何使用
- 1)您在您的网站上发布一个页面,并在我方平台配置完毕;
- 2)我们会周期性的将报表事件(打开/点击/硬退/软退等)按照固定格式推送到该页面上;
- 格式请参考本文下方的#Webhook数据包结构说明
- 3)您记录下相关事件,并更新数据库;
注:关于同步频率的说明: 暂定数据同步周期为每1000条状态事件或每30秒。也就是说:状态事件累计满1000条,同步一次,如果30秒内没有积累满1000条,则也同步一次。
Webhook数据包结构说明
- 1)数据包是采取json格式推送;
- 2)每次同步的数据包中会含有多个或一个状态消息;
- 3)每个状态消息代表一个事件,由若干个字段组成,传递该事件的相关信息;
- 4)系统支持的事件列表请参考#Webhook事件说明,系统支持的字段列表请参考#Webhook字段说明
- 5)样例数据包如下(为了阅读方便,http消息体刻意进行了换行,实际消息体数据应该在一行中)
POST /easeyewebhookreceive/receive.aspx?id=9787435 HTTP/1.1 content-type: application/x-www-form-urlencoded User-Agent: Java/1.6.0_43 Host: www.yiyetest.com Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2 Connection: keep-alive Content-Length: 1482 [{"Email":"a@b.com","EventCode":"Bounced","EventType":"3","TriggeredDateTime":"\/Date(1465794669959+0
800)\/","Reason":"101","SenderEmail":"test@edm.test.com","SentMailListName":"","UniqueMsgID":"7594973
56"},{"Email":"c@d.com","EventCode":"Delivered","EventType":"3","ReceiveServer":"mail.d.com[1.1.1.1]:
25","SenderEmail":"test@edm.test.com","SentMailListName":"","SubmitDateTime":"\/Date(1486453397000+08
00)\/","TriggeredDateTime":"\/Date(1486453483000+0800)\/","UniqueMsgID":"5817075077531"},{"BrowserTyp
e":"","DeliveredTime":"\/Date(1486354807000+0800)\/","Email":"c@d.com","EventCode":"Opened","EventTyp
e":"3","IP":"2.2.2.2","Platform":"","SentMailListName":"","SubmitDateTime":"\/Date(1486354700000+0800
)\/","TriggeredDateTime":"\/Date(1486453986718+0800)\/","UA":"Mozilla\/5.0 (Windows NT 6.1) AppleWebK
it\/537.36 (KHTML, like Gecko) Chrome\/31.0.1650.16 Safari\/537.36","UniqueMsgID":"5817071237437"},{"
BrowserType":"unknown","DeliveredTime":"\/Date(1486521456000+0800)\/","Email":"c@d.com","EventCode":"
Clicked","EventType":"3","IP":"2.2.2.2","Link":"http:\/\/www.baidu.com\/index.html","Platform":"Andro
id","SentMailListName":"","SubmitDateTime":"\/Date(1486521456000+0800)\/","Title":"","TriggeredDateTi
me":"\/Date(1486521640161+0800)\/","UA":"Mozilla\/5.0 (Linux; Android 4.4.4; iToolsVM Build\/KTU84P)
AppleWebKit\/537.36 (KHTML, like Gecko) Version\/4.0 Chrome\/33.0.0.0 Mobile Safari\/537.36 MicroMess
enger\/6.3.31.940 NetType\/WIFI Language\/zh_CN","UniqueMsgID":""}]
Webhook事件说明
1)不同事件里面的字段不尽相同;
2)在一个事件里面的某些字段值可能为空;
- 邮件任务有两种提交方式:列表方式提交(人工或者Webservice接口)和SMTP方式提交;
- 显然,某些字段仅仅在特定提交方式下有意义;
- 比如字段SentMailListName仅仅在列表方式提交下才有意义,其他方式下的事件即便包含该字段,其值也是空;
Dropped事件
- 事件说明:由于各种原因(具体请参考#Reason中说明),导致该邮件压根儿没有发送;
- 事件涉及的字段:
- EventType, EventCode, Email, TriggeredDateTime, Reason, SentMailListName, UniqueMsgID, SenderEmail
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"Dropped", "Email":"test@test.easeye.net", "EventType":"3", "Reason":"112", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"", "TriggeredDateTime":"\/Date(1486396335000+0800)\/", "UniqueMsgID":"23230232329" } ] 列表方式提交的样例: [ { "EventCode":"Dropped", "Email":"test@test.easeye.net", "EventType":"1", "Reason":"110", "SenderEmail":"", "SentMailListName":"newsletter201607", "TriggeredDateTime":"\/Date(1486444009027+0800)\/", "UniqueMsgID":"" } ]
Bounced事件
- 事件说明:由于各种原因(具体请参考#Reason中说明),导致该邮件发送失败;
- 事件涉及的字段:
- EventCode, Email, EventType, FailedCause, Reason, SenderEmail, SentMailListName, SubmitDateTime, TriggeredDateTime, UniqueMsgID
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"Bounced", "Email":"test@test.easeye.net", "EventType":"3", "Reason":"100", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"", "SubmitDateTime":"\/Date(1486389860000+0800)\/", "TriggeredDateTime":"\/Date(1486393164000+0800)\/", "FailedCause":"Cjx0ZXN0QHRlc3QuZWFzZXllLm5ldD46IGhvc3QgdGVzdC5lYXNleWUubmV0WzEuMS4xLjFdIHNhaWQ6IDU1NCBJbnZhbGlkCiAgICByZWNpcGllbnQgKGluIHJlcGx5IHRvIFJDUFQgVE8gY29tbWFuZCkKCgo=", "UniqueMsgID":"892032348" } ] 列表方式提交的样例: [ { "EventCode":"Bounced", "Email":"test@test.easeye.net", "EventType":"1", "FailedCause":"Cjx0ZXN0QHRlc3QuZWFzZXllLm5ldD46IGhvc3QgdGVzdC5lYXNleWUubmV0WzEuMS4xLjFdIHNhaWQ6IDU1NCBtYWlsYm94CiAgICBpcyBmdWxsLiAoaW4gcmVwbHkgdG8gUkNQVCBUTyBjb21tYW5kKQoKCg==", "Reason":"101", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"newsletter201607", "SubmitDateTime":"\/Date(1486388353000+0800)\/", "TriggeredDateTime":"\/Date(1486393139000+0800)\/", "UniqueMsgID":"" } ]
Delivered事件
- 事件说明:已送达,邮件已投递到联系人邮箱。
- 事件涉及的字段:
- EventCode, Email, EventType, ReceiveServer, SenderEmail, SentMailListName, SubmitDateTime, TriggeredDateTime, UniqueMsgID
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"Delivered", "Email":"test@test.easeye.net", "EventType":"5", "ReceiveServer":"test.easeye.net[1.1.1.1]:25", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"", "SubmitDateTime":"\/Date(1486392742000+0800)\/", "TriggeredDateTime":"\/Date(1486392762000+0800)\/", "UniqueMsgID":"892052719" } ] 列表方式提交的样例: [ { "EventCode":"Delivered", "Email":"test@test.easeye.net", "EventType":"1", "ReceiveServer":"test.easeye.net[1.1.1.1]:25", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"newsletter201607", "SubmitDateTime":"\/Date(1486388353000+0800)\/", "TriggeredDateTime":"\/Date(1486393011000+0800)\/", "UniqueMsgID":"" } ]
Opened事件
- 事件说明:联系人打开了邮件;每次打开都会产生一个此类状态事件;
邮件打开事件有可能会捕捉不到(比如邮件不显示图片),所以可能会出现同一个联系人有点击事件而没有打开事件,请注意处理。
- 事件涉及的字段:
- EventCode, BrowserType, DeliveredTime, Email, EventType, IP, Platform, SentMailListName, SubmitDateTime, TriggeredDateTime, UA, UniqueMsgID
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"Opened", "BrowserType":"", "DeliveredTime":"\/Date(1486611827000+0800)\/", "Email":"test@test.easeye.net", "EventType":"3", "IP":"1.1.1.1", "Platform":"", "SentMailListName":"", "SubmitDateTime":"\/Date(1486611827000+0800)\/", "TriggeredDateTime":"\/Date(1486615863073+0800)\/", "UA":"Mozilla\/5.0 (Windows NT 6.3; WOW64) AppleWebKit\/537.36 (KHTML,like Gecko) Chrome\/45.0.2454.101 Safari\/537.36", "UniqueMsgID":"1809631" } ] 列表方式提交的样例: [ { "EventCode":"Opened", "BrowserType":"", "DeliveredTime":"\/Date(1485330908000+0800)\/", "Email":"test@test.easeye.net", "EventType":"1", "IP":"1.1.1.1", "Platform":"", "SentMailListName":"newsletter201607", "SubmitDateTime":"\/Date(1485326092000+0800)\/", "TriggeredDateTime":"\/Date(1486610647942+0800)\/", "UA":"Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit\/602.3.12 (KHTML,like Gecko)", "UniqueMsgID":"" } ]
Clicked事件
- 事件说明:联系人点击了邮件内的某个链接(开启链接跟踪才会产生此数据);每次点击都会产生一个此类状态消息。
- 事件涉及的字段:
- EventCode, BrowserType, DeliveredTime, Email, EventType, IP, Link, Platform, SentMailListName, SubmitDateTime, Title, TriggeredDateTime, UA, UniqueMsgID
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"Clicked", "BrowserType":"Mobile Safari", "DeliveredTime":"\/Date(1486540134000+0800)\/", "Email":"test@test.easeye.net", "EventType":"3", "IP":"1.1.1.1", "Link":"https:\/\/www.baidu.com\/def\/index.htm?ab=0&cd=ef", "Platform":"iOS", "SentMailListName":"", "SubmitDateTime":"\/Date(1486540134000+0800)\/", "Title":"", "TriggeredDateTime":"\/Date(1486616528649+0800)\/", "UA":"Mozilla\/5.0 (iPhone; CPU iPhone OS 10_2 like Mac OS X) AppleWebKit\/602.3.12 (KHTML,like Gecko) Mobile\/14C92 (4347662848)", "UniqueMsgID":"5611974" } ] 列表方式提交的样例: [ { "EventCode":"Clicked", "BrowserType":"Chrome", "DeliveredTime":"\/Date(1486197815000+0800)\/", "Email":"test@test.easeye.net", "EventType":"1", "IP":"1.1.1.1", "Link":"http:\/\/www.baidu.com\/def\/adbc\/?a=b&c=d&e=f&g=h", "Platform":"Windows 7", "SentMailListName":"newsletter201607", "SubmitDateTime":"\/Date(1486196768000+0800)\/", "Title":"", "TriggeredDateTime":"\/Date(1486610529438+0800)\/", "UA":"Mozilla\/5.0 (Windows NT 6.1; WOW64) AppleWebKit\/537.36 (KHTML,like Gecko) Chrome\/56.0.2924.87 Safari\/537.36", "UniqueMsgID":"" } ]
Unsubscribed事件
- 事件说明:联系人退订,不再接收营销邮件。
- 事件涉及的字段:
- EventCode, Email, EventType, SentMailListName, TriggeredDateTime, UniqueMsgID
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"Unsubscribed", "Email":"test@test.easeye.net", "EventType":"3", "SentMailListName":"", "TriggeredDateTime":"\/Date(1486401724233+0800)\/", "UniqueMsgID":"1795046" } ] 列表方式提交的样例: [ { "EventCode":"Unsubscribed", "Email":"test@test.easeye.net", "EventType":"1", "SentMailListName":"newsletter201607", "TriggeredDateTime":"\/Date(1486395326733+0800)\/", "UniqueMsgID":"" } ]
SpamReport事件
- 事件说明:垃圾邮件投诉,联系人向ESP举报此邮件是垃圾邮件。。
- 事件涉及的字段:
- EventCode, Email, EventType, SenderEmail, SentMailListName, TriggeredDateTime, UniqueMsgID
- 事件样例:
SMTP方式提交的样例: [ { "EventCode":"SpamReport", "Email":"test@test.easeye.net", "EventType":"5", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"", "TriggeredDateTime":"\/Date(1486430799000+0800)\/", "UniqueMsgID":"891025625" } ] 列表方式提交的样例: [ { "EventCode":"SpamReport", "Email":"test@test.easeye.net", "EventType":"1", "SenderEmail":"service@trigger.easeye.com", "SentMailListName":"newsletter201607", "TriggeredDateTime":"\/Date(1486431684837+0800)\/", "UniqueMsgID":"" } ]
Webhook字段说明
EventType
邮件任务的提交类型;
- 1:列表方式提交的邮件;
- 3:事务类SMTP邮件(默认走27端口);
- 5:营销类SMTP邮件(默认走26端口);
EventCode
状态事件标示,代表此事件是什么类型的事件,目前支持的事件名称请参考#Webhook事件说明;
SenderEmail
发送人Email
接收方Email
UniqueMsgID
本次邮件发送行为的唯一标示,具体请参考smtp接口说明#X-Easeye-UniqueMsgID头部
SentMailListName
邮件列表的名称;
联系人邮件地址
TriggeredDateTime
状态产生的时间,格式为UTC时区1970年1月1日到现在的毫秒数+时区,样例:\/Date(1367040000000+0800)\/ 。
Reason
过滤或者投递失败的原因,如下:
属于#Bounced事件的类别
- 100:硬退:本次投递过程中投递失败,原因是因为该地址是无效地址;
- 101:软退:本次投递过程中投递失败,原因是接收方服务器无法链接成功或者拒信(邮箱已满,或者设置了黑名单,或者判定为垃圾邮件;
属于#Dropped事件的类别
- 110:硬退过滤:历史上判定为无效地址而过滤;
- 111:发送策略过滤:比如使用了我司的新版活跃度策略,按照策略要求被过滤的用户;
- 112:过期:在有效期内未能投递完毕;
- 114:缺少必要数据过滤:比如模板中存在临时标签,但却没有将某个/某些联系人对应的标签值传过来,这些人就不会发送;
- 210:退订过滤:历史上判定为退订用户而过滤;
IP
事件发生的源IP;
UA
触发该事件的浏览器或者客户端标识(UserAgent);
LINK
该事件的相关链接;
FailedCause
投递失败的原因,需要进行base64解码;
SubmitDateTime
该邮件的提交时间,格式同#TriggeredDateTime
ReceiveServer
接收该信件的邮件服务器
Platform
平台类型
BrowserType
浏览器类型
DeliveredTime
投递成功的时间,格式同#TriggeredDateTime
Title
点击事件中,该链接对应的Title属性,方便区分链接地址相同,但链接不同的情况;