Webhook接口说明

来自亿业科技接口
跳转至: 导航搜索

如何使用

1)您在您的网站上发布一个页面,并在我方平台配置完毕;
具体操作方法请参考开发前准备工作中的Webhook配置
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/json;charset=UTF-8
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","TriggeredDateTimeV2":"2023-10-31 13:54:31",
"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":"","SubmitDateTimeV2":"2023-10-31 13:54:31",
"TriggeredDateTimeV2":"2023-10-31 13:54:31","UniqueMsgID":"5817075077531"},{"BrowserTyp
e":"","DeliveredTime":"2023-10-31 13:54:31","Email":"c@d.com","EventCode":"Opened","EventTyp
e":"3","IP":"2.2.2.2","Platform":"","SentMailListName":"","SubmitDateTimeV2":"2023-10-31 13:54:31",
"TriggeredDateTimeV2":"2023-10-31 13:54:31","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","DeliveredTimeV2":"2023-10-31 13:54:31","Email":"c@d.com","EventCode":"
Clicked","EventType":"3","IP":"2.2.2.2","Link":"http:\/\/www.baidu.com\/index.html","Platform":"Andro
id","SentMailListName":"","SubmitDateTimeV2":"2023-10-31 13:54:31","Title":"","TriggeredDateTi
me":"2023-10-31 13:54:31","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)不同事件里面的字段不尽相同;

显然,根据字面意思,可以知道Reason字段是不可能出现在#Opened事件中;

2)在一个事件里面的某些字段值可能为空;

邮件任务有两种提交方式:列表方式提交(人工或者Webservice接口)和SMTP方式提交;
显然,某些字段仅仅在特定提交方式下有意义;
比如字段SentMailListName仅仅在列表方式提交下才有意义,其他方式下的事件即便包含该字段,其值也是空;

Dropped事件

事件说明:由于各种原因(具体请参考#Reason中说明),导致该邮件压根儿没有发送;
事件涉及的字段:
EventType, EventCode, Email, TriggeredDateTimeV2, Reason, SentMailListName, UniqueMsgID, SenderEmail
事件样例:
SMTP方式提交的样例:
[
   {
       "EventCode":"Dropped",
       "Email":"test@test.easeye.net",
       "EventType":"3",
       "Reason":"112",
       "SenderEmail":"service@trigger.easeye.com",
       "SentMailListName":"",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":"23230232329"
   }
]
列表方式提交的样例:
[
   {
       "EventCode":"Dropped",
       "Email":"test@test.easeye.net",
       "EventType":"1",
       "Reason":"110",
       "SenderEmail":"",
       "SentMailListName":"newsletter201607",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":""
   }
]

Bounced事件

事件说明:由于各种原因(具体请参考#Reason中说明),导致该邮件发送失败;
事件涉及的字段:
EventCode, Email, EventType, FailedCause, Reason, SenderEmail, SentMailListName, SubmitDateTimeV2, TriggeredDateTimeV2, UniqueMsgID
事件样例:
SMTP方式提交的样例:
[
   {
       "EventCode":"Bounced",
       "Email":"test@test.easeye.net",
       "EventType":"3",
       "Reason":"100",
       "SenderEmail":"service@trigger.easeye.com",
       "SentMailListName":"",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "FailedCause":"Cjx0ZXN0QHRlc3QuZWFzZXllLm5ldD46IGhvc3QgdGVzdC5lYXNleWUubmV0WzEuMS4xLjFdIHNhaWQ6IDU1NCBJbnZhbGlkCiAgICByZWNpcGllbnQgKGluIHJlcGx5IHRvIFJDUFQgVE8gY29tbWFuZCkKCgo=",
       "UniqueMsgID":"892032348"
   }
]
列表方式提交的样例:
[
   {
       "EventCode":"Bounced",
       "Email":"test@test.easeye.net",
       "EventType":"1",
       "FailedCause":"Cjx0ZXN0QHRlc3QuZWFzZXllLm5ldD46IGhvc3QgdGVzdC5lYXNleWUubmV0WzEuMS4xLjFdIHNhaWQ6IDU1NCBtYWlsYm94CiAgICBpcyBmdWxsLiAoaW4gcmVwbHkgdG8gUkNQVCBUTyBjb21tYW5kKQoKCg==",
       "Reason":"101",
       "SenderEmail":"service@trigger.easeye.com",
       "SentMailListName":"newsletter201607",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":""
   }
]

Delivered事件

事件说明:已送达,邮件已投递到联系人邮箱。
事件涉及的字段:
EventCode, Email, EventType, ReceiveServer, SenderEmail, SentMailListName, SubmitDateTimeV2, TriggeredDateTimeV2, 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":"",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "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",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":""
   }
]

Opened事件

事件说明:联系人打开了邮件;每次打开都会产生一个此类状态事件;
 邮件打开事件有可能会捕捉不到(比如邮件不显示图片),所以可能会出现同一个联系人有点击事件而没有打开事件,请注意处理。
事件涉及的字段:
EventCode, BrowserType, DeliveredTimeV2, Email, EventType, IP, Platform, SentMailListName, SubmitDateTimeV2, TriggeredDateTimeV2, UA, UniqueMsgID
事件样例:
SMTP方式提交的样例:
[
   {
       "EventCode":"Opened",
       "BrowserType":"",
       "DeliveredTimeV2":"2023-10-31 13:54:31",
       "Email":"test@test.easeye.net",
       "EventType":"3",
       "IP":"1.1.1.1",
       "Platform":"",
       "SentMailListName":"",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "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":"",
       "DeliveredTimeV2":"2023-10-31 13:54:31",
       "Email":"test@test.easeye.net",
       "EventType":"1",
       "IP":"1.1.1.1",
       "Platform":"",
       "SentMailListName":"newsletter201607",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UA":"Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_12_2) AppleWebKit\/602.3.12 (KHTML,like Gecko)",
       "UniqueMsgID":""
   }
]

Clicked事件

事件说明:联系人点击了邮件内的某个链接(开启链接跟踪才会产生此数据);每次点击都会产生一个此类状态消息。
事件涉及的字段:
EventCode, BrowserType, DeliveredTimeV2, Email, EventType, IP, Link, Platform, SentMailListName, SubmitDateTimeV2, Title, TriggeredDateTimeV2, UA, UniqueMsgID
事件样例:
SMTP方式提交的样例:
[
   {
       "EventCode":"Clicked",
       "BrowserType":"Mobile Safari",
       "DeliveredTimeV2":"2023-10-31 13:54:31",
       "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":"",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "Title":"",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "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",
       "DeliveredTimeV2":"2023-10-31 13:54:31",
       "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",
       "SubmitDateTimeV2":"2023-10-31 13:54:31",
       "Title":"",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "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, TriggeredDateTimeV2, UniqueMsgID
事件样例:
SMTP方式提交的样例:
[
   {
       "EventCode":"Unsubscribed",
       "Email":"test@test.easeye.net",
       "EventType":"3",
       "SentMailListName":"",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":"1795046"
   }
]
列表方式提交的样例:
[
   {
       "EventCode":"Unsubscribed",
       "Email":"test@test.easeye.net",
       "EventType":"1",
       "SentMailListName":"newsletter201607",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":""
   }
]

SpamReport事件

事件说明:垃圾邮件投诉,联系人向ESP举报此邮件是垃圾邮件。。
事件涉及的字段:
EventCode, Email, EventType, SenderEmail, SentMailListName, TriggeredDateTimeV2, UniqueMsgID
事件样例:
SMTP方式提交的样例:
[
   {
       "EventCode":"SpamReport",
       "Email":"test@test.easeye.net",
       "EventType":"5",
       "SenderEmail":"service@trigger.easeye.com",
       "SentMailListName":"",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":"891025625"
   }
]
列表方式提交的样例:
[
   {
       "EventCode":"SpamReport",
       "Email":"test@test.easeye.net",
       "EventType":"1",
       "SenderEmail":"service@trigger.easeye.com",
       "SentMailListName":"newsletter201607",
       "TriggeredDateTimeV2":"2023-10-31 13:54:31",
       "UniqueMsgID":""
   }
]

Webhook字段说明

EventType

邮件任务的提交类型;

1:列表方式提交的邮件;
3:事务类SMTP邮件(默认走27端口);
5:营销类SMTP邮件(默认走26端口);

EventCode

状态事件标示,代表此事件是什么类型的事件,目前支持的事件名称请参考#Webhook事件说明

SenderEmail

发送人Email

Email

接收方Email

UniqueMsgID

本次邮件发送行为的唯一标示,具体请参考smtp接口说明#X-Easeye-UniqueMsgID头部

SentMailListName

邮件列表的名称;

Email

联系人邮件地址

TriggeredDateTimeV2

状态产生的时间,格式为yyyy-MM-dd HH:mm:ss,样例:2023-10-31 13:54:31 。

Reason

过滤或者投递失败的原因,如下:
属于#Bounced事件的类别

100:硬退:本次投递过程中投递失败,原因是因为该地址是无效地址;
101:软退:本次投递过程中投递失败,原因是接收方服务器无法链接成功或者拒信(邮箱已满,或者设置了黑名单,或者判定为垃圾邮件;

属于#Dropped事件的类别

110:硬退过滤:历史上判定为无效地址而过滤;
111:发送策略过滤:比如使用了我司的新版活跃度策略,按照策略要求被过滤的用户;
112:过期:在有效期内未能投递完毕;
114:缺少必要数据过滤:比如模板中存在临时标签,但却没有将某个/某些联系人对应的标签值传过来,这些人就不会发送;
210:退订过滤:历史上判定为退订用户而过滤;

IP

事件发生的源IP;

UA

触发该事件的浏览器或者客户端标识(UserAgent);

LINK

该事件的相关链接;

FailedCause

投递失败的原因,需要进行base64解码;

SubmitDateTimeV2

该邮件的提交时间,格式同#TriggeredDateTimeV2

ReceiveServer

接收该信件的邮件服务器

Platform

平台类型

BrowserType

浏览器类型

DeliveredTimeV2

投递成功的时间,格式同#TriggeredDateTimeV2

Title

点击事件中,该链接对应的Title属性,方便区分链接地址相同,但链接不同的情况;