获取收件人行为记录

Get subscriber activity 获取收件人行为记录

Activities接口集合 允许获得指定类型的收件人行为条目列表。例如，可以获得所有点击行为的细节列表. 此接口集合，由于其本质，为只读.

请求数据格式

请求URL参数:
参数 类型 描述
apiKey string 你的API Key, 需要验证. 必填.
date date 日期. 必填, 格式为YYYY-MM-DD.
channel string 限制返回值为指定通道. 仅适用于以下行为: 订阅，发送，点击，移除，退信，转化. 选填*. 默认通道为邮件. 有效值为：

    • 全部
    • 邮件
    • 短信/彩信
type string 需要返回的行为类型. 所有合法选项见下. 必填.
columns string 返回的列. 选填. 可以为以下两种之一:

    • 标准 (默认值)
    • 附加 (额外的 列 将在CSV中被返回- 详细信息见下)
returnTitle boolean 如设为true，将返回一列包含链接标题的额外信息. 此参数只影响行为：Clicks
returnGuid boolean 如设为true，将返回一列包含所发送邮件的“全域唯一标示符”GUID (Globally Unique Identifier),这个选项对以下两个行为类型没有影响：Subscriptions, Confirmations
tags string 逗号分隔标签列表. 选填. 如指定，只返回包含全部指定标签的消息. (每个逗号为’与’逻辑，对于’或’逻辑，需建立新的请求). 下列为有效参数: Sends, Opens, Clicks, Complaints, Removals, Bounces, Goals. 系统标签无法查找，如（API, D&D, A/B).
returnMessageContentId boolean 如设置为True, 将额外返回已发送消息内容ID列. 这个参数对订阅，确认和发送类型无影响.

系统支持统计的行为/任务数据类型:

类型 返回数据
Subscriptions 列表中新添加的收件人. 同样包括导入及手动添加的等.
Confirmations 订阅/注册确认. 此只应用于设置了双重选择(double opt-in)加入的列表.
Sends 向单个收件人发送邮件. 单个收件人可以收到多个邮件，这些发送行为都将被包括
Opens 打开邮件. 如果一个收件人多次打开一封电邮（相同或不同电邮)，这些打开行为都将被包括
Clicks 点击链接. 同上.
Complaints 投诉垃圾邮件.
Removals 退订以及从收件人列表中手动移除
Bounces 弹回
Goals 已发生的转化目标.

示例URL:

https://api.esv2.com/v2/Api/Activities?apiKey=YOUR_API_KEY_HERE&date=2011-11-25&type=Clickshttps://api.esv2.com/v2/Api/Activities?apiKey=YOUR_API_KEY_HERE&date=2011-11-26&type=Subscriptions&channel=SmsMmshttps://api.esv2.com/v2/Api/Activities?apiKey=YOUR_API_KEY_HERE&date=2011-11-25&type=Sends&returnGuid=true

应答

这种接口与其他接口不同的是返回的数据是以CSV格式，而不是XML。这是因为这些数据的数量通常会更大一些。CSV会减少管理成本，而且一般来说会更容易解析及操作。

应答内容类型应为“text/csv”。返回的数据包括具有各列名称的表头。CSV的格式被设置为：

  • Field separator字段分隔符: comma逗号 (,)
  • Quoting character引用符号: (“)
  • Escape character换码符: (“)
  • Encoding编码: UTF-8

返回列取决于请求的行为类型。所有有效行为类型，见下

订阅Subscriptions行为返回的列:

名称 类型 描述
Date datetime 订阅/注册日期.格式 YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
Phone int 收件人电话号码.
ListId int 列表标识ID.
ListName string 列表名称.
CustomSubscriberId string 收件人标识ID.
Channel string 订阅通道.*

* 只在Channel选项为’All’时返回

确认订阅/注册Confirmations行为返回的列:

名称 类型 描述
Date datetime 确认订阅/注册日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email.
ListId int 列表标识ID
ListName string 列表名称.
CustomSubscriberId string 收件人标识ID.

发送Sends行为返回的列:

名称 类型 描述
Date datetime 发送日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
Phone int 收件人电话号码.
MessageId int 已发送的邮件标识ID.
MessageSubject string 已发送邮件的标题.
CustomSubscriberId string 收件人标识ID.
Channel string 发送行为连接的通道.*
ListId int 列表标识ID.**
ListName string 列表名称.*
MessageGuid string 发送消息的“全域唯一标示符”GUID.***
*只在Channel选项为’All’时返回
** 额外的列
***只有当returnGuid参数被设为true时才会返回
打开Opens行为返回的列:
名称 类型 描述
Date datetime 打开日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email
MessageId int 已打开的邮件标识ID.
MessageSubject string 已打开邮件的标题.
CustomSubscriberId string 收件人标识ID.
ListId int 列表标识ID.*
ListName string 列表名称.*
MessageGuid string 发送消息的“全域唯一标示符”GUID.**
MessageContentId int 已打开的消息内容标识.***
* 额外的列
**只有当returnGuid参数被设为true时才会返回
*** 只在returnMessageContentId为true的时候返回
点击Clicks行为返回的列:
名称 类型 描述
Date datetime 点击日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
Phone int 收件人电话号码.
MessageId int 包含已被点击链接的邮件标识ID
MessageSubject string 包含已被点击链接的邮件标题.
Url string 点击链接的URL (如果链接是个性化的，则指的URL模板).
CustomSubscriberId string 收件人标识ID.
Channel string 点击行为连接的通道.*
Title string 点击链接的Title （如果Title属性出现在邮件HTML中）
ListId int 列表标识.**
ListName string 列表名称.**
MessageGuid string 发送消息的“全域唯一标示符”GUID.***
MessageContentId int 包含点击过链接的消息内容的标识.****
*只在Channel选项为’All’时返回
**额外的列
***只有当returnGuid参数被设为true时才会返回
****只在returnMessageContentId为true的时候返回

投诉Complaints行为返回的列:

名称 类型 描述
Date datetime 投诉日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
MessageId int 得到投诉的邮件标识ID.
MessageSubject string 得到投诉的邮件标题.
CustomSubscriberId string 收件人标识ID.
ListId int 列表标识ID.*
ListName string 列表名称.*
MessageGuid string 发送消息的“全域唯一标示符”GUID.*
MessageContentId int 被投诉消息的消息内容标识.***
* 额外的列
** 只有在returnGuid设置为true时返回.
*** 只有在returnMessageContentId设置为true时返回.

删除Removal原因:

名称 类型 描述
Date datetime 删除日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
Phone int 收件人电话号码.
Reason string 删除原因. 见下面所有可能的原因.
MessageId int 已删除消息标识ID. 选填 (一些删除原因与发送消息无关).
MessageSubject string 已删选消息的标题. 选填.
CustomSubscriberId string 收件人标识ID.
Channel string 发送行为连接的通道.*
ListId int 列表标识ID.**
ListName string 列表名称.**
MessageGuid string 发送消息的“全域唯一标示符”GUID.***
MessageContentId int 已删除消息的消息内容标识. 选填 (一些删除原因与发送消息无关).****
*只在Channel选项为’All’时返回
**额外的列
***只有在returnGuid设置为true时返回
****只有在returnMessageContentId设置为true时返回true

弹回行为返回的列:

名称 类型 描述
Date datetime 弹回日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
Phone int 收件人电话号码.
Reason string 弹回原因. 见下面所有可能的原因
MessageId int 弹回消息标识ID.
DiagnosticCode strig 弹回诊断码用来识别弹回类型. 选填 (如果弹回email不包含诊断码).
CustomSubscriberId string 收件人标识ID.
Channel string 发送行为连接的通道.*
ListId int 列表标识.**
ListName string 列表名称.**
MessageGuid string 发送消息的“全域唯一标示符”GUID.***
MessageContentId int 弹回消息的消息内容标识.****
*只在Channel选项为’All’时返回
**额外的列
***只有在returnGuid设置为true时返回
****只有在returnMessageContentId设置为true时返回true

目标转化行为返回的列:

名称 类型 描述
Date datetime 目标转化日期. 格式YYYY-MM-DD HH:MM:SS
Email string 收件人email地址.
Phone int 收件人电话号码.
MessageId int 达到转化目标的消息标识ID.
MessageSubject string 达到转化目标的消息标题.
GoalValue int 达到的转化目标值. 如没有指定转化目标值，则可用0代替.
GoalId int 目标转化标识.
CustomSubscriberId string 收件人标识ID.
Channel string 发送行为连接的通道.*
ListId int 列表标识.**
ListName string 列表名称.**
MessageGuid string 发送消息的“全域唯一标示符”GUID.***
MessageContentId int 达到转化目标值的消息内容标识.****
*只在Channel选项为’All’时返回
**额外的列
***只有在returnGuid设置为true时返回
****只有在returnMessageContentId设置为true时返回true

删除原因:

名称 描述
Subscriber 收件人通过点击系统生成的退订链接或ISP提供的一键退订按钮被删除.
User 收件人通过管理员操作删除.
Bounce 收件人因达到弹回上限而被自动删除.
Spam 收件人因被举报发送垃圾邮件而被自动删除.
UserUnknown 收件人因email地址不存在被自动删除(由于 “收件人不存在”产生的弹回).
Api 通过API删除收件人.

弹回原因:

名称 描述
UserUnknown Email地址不存在.
MailboxFull 收件人邮箱已满或暂时不可送达.
Blocked 已发送邮件被阻止, 可能由于包含垃圾内容.
OutOfOffice 自动回复“out of office”.
Unknown 无法判断
Other 其他弹回原因. 包含网络传输原因及邮件服务器故障等.

示例

请求:
GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Sends HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com
OK应答:
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/csv; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 2.0
X-AspNet-Version: 2.0.50727
Set-Cookie: TIMEZONE=Central European Standard Time; path=/
X-Powered-By: ASP.NET
Date: Thu, 08 Dec 2011 12:02:14 GMT
Content-Length: 463

Date,Email,MessageId,MessageSubject
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber
有额外列的请求:
GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Sends&columns=Extended HTTP/1.1 

Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com
OK应答:
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/csv; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 2.0
X-AspNet-Version: 2.0.50727
Set-Cookie: TIMEZONE=Central European Standard Time; path=/
X-Powered-By: ASP.NET
Date: Thu, 08 Dec 2011 12:02:14 GMT
Content-Length: 523Date,Email,MessageId,MessageSubject,ListId,ListName
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject,123,some list name
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject,123,some list name
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject,123,some list name
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject,123,some list name
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber,456,other list
有GUID的请求:
GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Sends&returnGuid=true HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com
OK应答:
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/csv; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 2.0
X-AspNet-Version: 2.0.50727
Set-Cookie: TIMEZONE=Central European Standard Time; path=/
X-Powered-By: ASP.NET
Date: Thu, 08 Dec 2011 12:02:14 GMT
Content-Length: 523Date,Email,MessageId,MessageSubject,MessageGuid
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject,c7015756-95f3-4509-8c6c-759feec48f91
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject,f1184a56-86d5-461e-ac1b-0000040bb27b
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject,d56a7c29-885f-4fcc-8f85-00001392908b
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject,180668e3-7ea1-4f12-83b3-000004f11566
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber,a01b5b76-c61d-4533-bc3f-0000142e085d

有消息内容id的请求:

GET https://api.esv2.com/v2/Api/Activities?date=2010-10-01&apiKey=test_api_key1&type=Opens&returnMessageContentId=true&returnSegmentId=true HTTP/1.1 

Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com
OK应答:
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/csv; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 2.0
X-AspNet-Version: 2.0.50727
Set-Cookie: TIMEZONE=Central European Standard Time; path=/
X-Powered-By: ASP.NET
Date: Thu, 08 Dec 2011 12:02:14 GMT
Content-Length: 523Date,Email,MessageId,MessageSubject,CustomSubscriberId,MessageGuid
2010-10-01 17:10:00,test1@yahoo.com,1168,some test subject,c7015756-95f3-4509-8c6c-759feec48f91,,1222
2010-10-01 17:10:00,test2@yahoo.com,1168,some test subject,f1184a56-86d5-461e-ac1b-0000040bb27b,,1222
2010-10-01 17:11:00,test3@yahoo.com,1168,some test subject,d56a7c29-885f-4fcc-8f85-00001392908b,,1222
2010-10-01 17:11:00,test4@yahoo.com,1168,some test subject,180668e3-7ea1-4f12-83b3-000004f11566,,1222
2010-10-01 19:20:00,john.doe@gmail.com,1170,Hello dear subscriber,a01b5b76-c61d-4533-bc3f-0000142e085d,,1224