获取列表统计数据

Get subscriber statistics 获取列表统计数据

SubscriberStatistics接口允许获取关于收件人列表的各种表现数据。这意味着你可以获知在某个时间段内列表的大小，收件人数量，收件人的变化（加入、退订）等。

请求数据格式

请求 URL 参数:
参数 类型 备注
apiKey string 您的API Key，为了认证身份。必填.
startDate date 起始日期 必填，默认使用业务单元的建立日期 YYYY-MM-DD 格式.
endDate date 结束日期 必填，默认使用当天日期. YYYY-MM-DD 格式.
scope string “限制范围” 选填 如果未指定, 没有任何限制将被应用 (整个业务单元的数据将被返回).

可选的限制范围:

    • List 收件人列表 – 只有关于指定收件人列表的结果
    • Domain 域名 – 只有关于指定域名的结果
    • DomainFamily 域名家族 – 只有关于指定域名家族的结果*
    • MessageType 邮件类型 – 只有关于指定邮件类型的结果**
    • Ip – 只有关于指定IP的结果
    • Segment 收件人细分 – 只有关于指定收件人细分的结果
    • Vendor 收件人来源 – 只有关于指定收件人来源的结果
    • Tag 标签 – 有关于有指定标签的邮件的结果
    • SendTimeOptimization 发送时间优化 – 只有设置了特定发送时间优化方式的邮件结果***
    • TimeTravelOptimization 时区自适应 – 只有设置了特定的时区自适应优化方式的邮件结果 ****
    • ReadingEnvironment 开信环境 – 只有在特定开信环境下的结果*****
scopeValue string “限制范围” 参数. 如果scope被指定，那么此参数也需填写. 这是一个复杂的参数，类型取决于所选的限制范围:

    • List 收件人列表 – 收件人列表ID, int, e.g. 123
    • Domain 域名 – 域名名称, string, e.g. domain.com
    • DomainFamily 域名家族 – 域名家族名称, string, e.g. Gmail*
    • MessageType 邮件类型 – 邮件类型名称, string, e.g. Newsletter**
    • Ip – IP 通道, string, e.g. 11.22.33.44
    • Segment 收件人细分 – 收件人细分ID, int, e.g. 123
    • Vendor 收件人来源 – 收件人来源名称, string, e.g. foobar
    • Tag 标签 – 标签名称,e.g. holidays.
    • SendTimeOptimization 发送时间优化 – 只有设置了特定发送时间优化方式的邮件结果***
    • TimeTravelOptimization 时区自适应 – 有设置了特定的时区自适应优化方式的邮件结果****
    • ReadingEnvironment 开信环境 – 只有在特定开信环境下的结果 *****
scope2 string “限制范围2”，运行规则有如“限制范围”.
scopeValue2 string “限制范围2” 参数. 运行规则有如“限制范围” 参数
grouping string “分组基于…” 参数. 选填. 如果未指定, 结果是基于整个业务单元的 (所有的数据和值将被显示于一行中).

可选的分组参数:

    • Date 日期
    • Month 月份
    • List 收件人列表
    • Segment 收件人细分
    • Ip
    • Domain 域名
    • DomainFamily 域名家族
    • Vendor 收件人来源
    • Tag 标签
    • SendTimeOptimization 发送时间优化
    • TimeTravelOptimization 时区自适应
    • ReadingEnvironment 开信环境

注意: 无法使用同一类的”限制范围“和”分组基于“。”限制范围“参数值必须不同于“分组基于”参数值。
*域名家族根据业务单元有所区别，甚至可以是自定义的。通常使用的域名家族有（但不必适用于您的业务单元）：Yahoo, Outlook.com, Gmail, AOL, Other.
 
**可用的消息类型有：邮件通讯, 自动回复, 触发式邮件, 事务性邮件, 确认邮件, 定时重复发送型邮件, 测试邮件.
 
***可使用的 SendTimeOptimization（发送时间优化）邮件设置包含:  OptimizationNotUsed – 未应用发送时间优化, TimeOptimized – 应用发送时间优化的发送时间, TimeNotOptimized – 未应用发送时间优化的发送时间.
 
****可使用的TimeTravelOptimization message （时区自适应）设置包含: OptimizationNotUsed, – 未应用时区自适应, TimeOptimized – 应用时区自适应的发送时间, TimeNotOptimized – 未应用时区自适应的发送时间.
 
*****可使用的 ReadingEnvironment （开信环境）值包含: Other – 其他, Desktop – PC端, Mobile – 移动端, Webmail – 网页邮箱, NoActivity -无活动记录.

示例:

https://api.esv2.com/v2/Api/SubscriberStatistics?apiKey=YOUR_API_KEY_HEREhttps://api.esv2.com/v2/Api/SubscriberStatistics?apiKey=YOUR_API_KEY_HERE&scope=List&scopeValue=1&grouping=Vendor

应答

应答数据元素:
元素/属性 类型 描述
SubscriberStatistics array[complex] SubscriberStatistic 元素组成的数组.
SubscriberStatistic 子元素:
元素/属性 类型 描述
IsSummaryRow boolean 如设为true, 将突出汇总行 (值为其他行值的总和).*
Date date 日期. 如果分组基于日期，则将被作为返回值.
Month string 月度将以日期范围形式呈现. 如果分组基于月度，则将被作为返回值.
例如: 2010-01-01 : 2010-01-31
ListId int 收件人列表ID. 如果分组基于收件人列表，则将被作为返回值.
ListName string 收件人列表名称. 如果分组基于收件人列表，则将被作为返回值.
SegmentId int 收件人细分ID. 如果分组基于收件人细分，则将被作为返回值. 且对那些未被划分到任何收件人细分中的收件人将单独划分一行，该行的返回值为”-”.
SegmentName string 收件人细分名称. 如果分组基于收件人细分，则将被作为返回值. 且对那些未被划分到任何收件人细分中的收件人将单独划分一行，该行的返回值为”-”.
Ip string IP通道地址. 如果分组基于IP，则将被作为返回值.
Domain string 域名名称. 如果分组基于域名，则将被作为返回值.
DomainFamily string 域名家族名称. 如果分组基于域名家族，则将被作为返回值.
Vendor string 收件人来源名称. 如果分组基于订阅来源，则将被作为返回值. 且对那些没有来源的收件人将单独划分一行，该行的返回值为”-”.
SendTimeOptimization string 发送时间优化. 如果分组基于发送时间优化，则将被作为返回值. 分组基于：未应用发送时间优化OptimizationNotUsed，应用发送时间优化的发送时间TimeOptimized，未应用发送时间优化的发送时间TimeNotOptimized，如都不属于以上分组将被划分为 ”-”.
TimeTravelOptimization string 时区自适应. 如果分组基于时区自适应，则将被作为返回值. 分组基于：未应用时区自适应OptimizationNotUsed，应用时区自适应的发送时间TimeOptimized，未应用时区自适应的发送时间TimeNotOptimized，如都不属于以上分组将被划分为 ”-”.
ReadingEnvironment string 开信环境. 如果分组基于开信环境，则将被作为返回值. 分组基于：其它Other, 移动端Mobile, PC端Desktop, 网页邮箱WebMail, 无活动记录NoActivity，如都不属于以上分组将被划分为 ”-”.
ListSize int 列表大小.
Growth int 列表大小改变情况（增加/减少）.
Added int 收件人增长总数.
AddedUi int 通过ExpertSender后台管理员操作添加的收件人数.
AddedImport int 通过手动或自动导入方式添加的收件人数.
AddedApi int 通过API添加的收件人数.
AddedWeb int 通过页面表单添加的收件人数.
Removed int 收件人减少总数.
RemovedOptOut int 通过点击退订链接移除的收件人数.
RemovedUser int 通过ExpertSender后台管理员操作移除的收件人数.
RemovedBounceLimit int 通过到达退信上线移除的收件人数.
RemovedSpam int 通过投诉垃圾邮件移除的收件人数.
RemovedUserUnknown int 通过退信类型User Unknown（Email不存在）而被移除的收件人数.
RemovedBlacklist int 由于被放入黑名单而同时被移除的收件人数.
RemovedApi int 通过API移除的收件人数.

*汇总行并不包含“分组基于”的参数 (如. 日期, 月份).

示例

请求 (没有分组基于):
GET https://api.esv2.com/v2/Api/SubscriberStatistics?apiKey=test_api_key1&scope=List&scopeValue=1&scope2=DomainFamily&scopeValue2=Gmail HTTP/1.1

Accept-Encoding: gzip,deflate
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
OK 应答:
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 5.2
X-AspNet-Version: 4.0.30319
Set-Cookie: TEMP_DATA=b8567a11-cbb2-4525-b355-782b8b3ea005; path=/
X-Powered-By: ASP.NET
Date: Wed, 29 Jul 2015 14:44:34 GMT
Content-Length: 870<ApiResponse
xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”>
 <Data>
  <SubscriberStatistics>
   <SubscriberStatistic>
    <IsSummaryRow>true</IsSummaryRow>
    <ListSize>469</ListSize>
    <Growth>469</Growth>
    <Added>470</Added>
    <AddedUi>0</AddedUi>
    <AddedImport>437</AddedImport>
    <AddedApi>0</AddedApi>
    <AddedWeb>0</AddedWeb>
    <Removed>1</Removed>
    <RemovedOptOut>1</RemovedOptOut>
    <RemovedUser>0</RemovedUser>
    <RemovedBounceLimit>0</RemovedBounceLimit>
    <RemovedSpam>0</RemovedSpam>
    <RemovedUserUnknown>0</RemovedUserUnknown>
    <RemovedBlacklist>0</RemovedBlacklist>
    <RemovedApi>0</RemovedApi>
   </SubscriberStatistic>
  </SubscriberStatistics>
 </Data>
</ApiResponse>