获取收件人信息

Get subscriber information 获取收件人信息

获取单个收件人Email地址的多种细节描述信息。获取信息可以有以下四个选择

 简短信息 含禁止列表的简短信息  全部信息 任务历史
    • Email地址在某收件人列表中的状态
    • 该Email地址是否存在于公共黑名单或是本业务单元的黑名单
    • Email地址在某收件人列表中的状态
      该
    • Email地址是否存在于公共黑名单中
    • Email地址存在于哪些禁止列表
  

    • Email地址在某收件人列表中的状态
    • 该Email地址是否存在于公共黑名单中
    • Email地址存在于哪些禁止列表
    • 收件人属性字段：
    • 名
    • 姓
    • 上次打开/点击邮件IP
    • 收件人ID
      来源
    • 所有属性字段
    • 关于收件人的所有任务信息，例如发送过邮件，点击，打开等
    • 这些信息将与ES后台中收件人明细中的信息一致

请求数据格式

参数 类型 描述
apiKey staring API key, 身份验证. 必填.
id integer 收件人ID.选填*
email string 收件人email. 必填.
phone string 收件人电话号码. 选填.*
customSubscriberId string 收件人标识ID.*
option string** 获取邮件有以下四种方法:

    • Short-简短信息
    • Long-含禁止列表的简短信息
    • Full-全部信息
    • EventHistory-任务历史

*以下其中一个条目须提供: 收件人ID， Email地址，电话号码，收件人标识ID. 系统会首先查找收件人ID， Email地址，电话号码，收件人标识ID. 如果请求提供超过一个条目系统则会采纳第一个值有效的条目而忽略其他条目.

**由于兼容的原因，你可以使用整型数据integer (1,2,3,4),而不是string. 但这种方法返回信息的选择方式应该考虑弃用.

应答

“Short”（简短信息）的应答

应答数据元素:
元素/属性 类型 描述
BlackListEmail boolean 如设为 “true” (注意小写!)，此参数意味着当前Email存在于黑名单中 （本业务单元或公共）.“false” 意味着Email没有在黑名单中。收件人没有Email则省略.
BlackListPhone boolean 如设为 “true” (注意小写!)，此参数意味着当前电话号码存在于黑名单中 （本业务单元或公共）.“false” 意味着电话号码没有在黑名单中。收件人没有电话号码则省略.
StateOnLists array[complex] StateOnList元素组成的数组
StateOnList子元素:
元素/属性 类型 描述
Email string 收件人email地址.
Phone integer 收件人电话号码.
ListId integer 收件人列表ID.
Name string 收件人列表名称.
Status string Email地址或电话号码在某收件人列表中的状态
SubscribedOn datetime 收件人订阅时间

(含禁止列表的简短信息)的应答

应答数据元素

元素/属性 类型 描述
BlackListEmail boolean 如设为 “true” (注意小写!)，此参数意味着当前Email存在于黑名单中 （本业务单元或公共）.“false” 意味着没有在黑名单中。收件人没有Email则省略.
BlackListPhone boolean 如设为 “true” (注意小写!)，此参数意味着当前电话号码存在于黑名单中 （本业务单元或公共）.“false” 意味着没有在黑名单中。收件人没有电话号码则省略.
StateOnLists array[complex] StateOnList元素组成的数组
SuppressionLists array[complex] SuppressionLists元素组成的数组

StateOnList子元素:

元素/属性 类型 描述
Email string 收件人email地址
Phone integer 收件人电话号码
ListId integer 收件人列表ID.
Name string 收件人列表名称.
Status string Email地址在某收件人列表中的状态
SubscribedOn datetime 收件人订阅时间

SuppressionList子元素:

元素/属性 类型 描述
Id integer Email所在禁止列表ID.
Name string Email所在禁止列表名称.
Type string 当前禁止列表类型. 有效值:

    • Email地址
    • 电话号码

“Full”（全部信息）的应答

应答数据元素:
元素/属性 类型 描述
BlackListEmail boolean 如设为 “true” (注意小写!)，此参数意味着当前Email存在于黑名单中 （本业务单元或公共）.“false” 意味着没有在黑名单中。收件人没有Email则省略.
BlackListPhone boolean 如设为 “true” (注意小写!)，此参数意味着当前电话号码存在于黑名单中 （本业务单元或公共）.“false” 意味着没有在黑名单中。收件人没有电话号码则省略.
StateOnLists array[complex] StateOnList元素组成的数组.
SuppressionLists array[complex] SuppressionList元素组成的数组
Firstname string 当前收件人名.
Lastname string 当前收件人姓.
Ip string 当前收件人IP. 依情况显示.选填
Id integer 当前收件人ID. 依情况显示.
Email string 收件人email地址.
Phone string 收件人电话号码.
CustomSubscriberId string 收件人标识ID.
Vendor string 当前收件人来源代码. 依情况显示.
Properties array[complex] 收件人属性字段组成的数组. 依情况显示

StateOnList子元素:

元素/属性 类型 描述
Email string 收件人email地址.
Phone integer 收件人电话号码.
ListId integer 收件人列表ID.
Name string 收件人列表名称.
Status string Email地址在某收件人列表中的状态
SubscribedOn datetime 收件人订阅时间

SuppressionList子元素:

元素/属性 类型 描述
Id integer Email所在禁止列表ID.
Name string Email所在禁止列表名称.
Type string 当前禁止列表类型. 有效值:

    • Email地址
    • 电话号码

Properties子元素:

元素/属性 类型 描述
Id integer 当前属性字段ID.
Source string 属性字段值来源信息. 所有可能的来源见下个表格.
DateTimeValue datetime 值. 仅用于日期及日期时间类型的属性字段值.
IntValue integer 值. 仅用于整型类型的属性字段值.
StringValue string 值. 仅用于字符串类型的属性字段值.
DecimalValue decimal 值. 仅用于货币类型的属性字段.
Type string 属性字段类型. 所有可能的属性字段类型见下下个表格.
FriendlyName string 自定义属性字段名称.
Description string 当前属性字段描述.
Name string 当前属性字段名称.
DefaultStringValue string 默认属性字段值. 仅用于字符串类型的属性字段.
DefaultIntValue integer 默认属性字段值. 仅用于整型类型的属性字段.
DefaultDateTimeValue datetime 默认属性字段值. 仅用于日期及日期时间类型的属性字段.
DefaultDecimalValue decimal 默认属性字段值. 仅用于货币类型的属性字段.


属性字段值来源: 

名称 描述
Web 利用页面表单添加/修改属性字段.
Panel 利用ExpertSender后台手动添加/修改属性字段
Import 导入时添加/修改属性字段.
Api 利用ExpertSender API添加/修改属性字段.
PrefCenter 通过点击用户偏好中心链接进入页面添加/修改属性字段.

属性字段类型:

名称 描述
Text 文本（字符串）属性.
Number 所有数字, 如 ‘0’ 或 ‘123’.
Money 两位小数数字, 如. ‘10.99’.
Url Url.
Date 日期，如. ‘2011-01-01’.
Datetime 日期和时间，如. ‘2011-01-01 12:00:00’.
SingleSelect 预设的几个值当中的单选值，如. ‘option 1’.
Boolean True/false.

“EventHistory”（任务历史）的应答

应答数据元素:
元素/属性 类型 描述
Events array[complex] 任务/行为组成的数组
Event子元素:
元素/属性 类型 描述
StartDate datetime 任务开始时间
EndDate datetime 任务结束时间
Channel string  任务包含的通道. 有效值:

    • Email地址
    • 短信/彩信
MessageType string 邮件的种类：Newsletter, Autoresponder（自动回复）, Trigger（触发）, Transactional（事务）等等
EventType string 任务的种类. 发送, 打开, 点击, 退信, 投诉, 确认, 退订.
EventCount integer StartDate(任务开始时间) 和 EndDate(任务结束时间) 之间的任务发生次数
MessageId integer 任务中牵涉的邮件ID
MessageSubject string 任务中牵涉的邮件标题

示例

获取订阅用户信息:


请求:

GET https://api.esv2.com/v2/Api/Subscribers?apiKey=test_api_key1&email=john%40yahoo.com&option=Full 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/xml; charset=utf-8
Content-Encoding: gzip
Vary: Accept-Encoding
Server: Microsoft-IIS/7.5
Set-Cookie: ASP.NET_SessionId=soo4fqb5y5cjbr3wimnyelb3; path=/; HttpOnly
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Mon, 25 Apr 2016 16:07:21 GMT
Content-Length: 421

<ApiResponse xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”
xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
 <Data>
  <BlackListEmail>false</BlackListEmail>
  <BlackListPhone>false</BlackListPhone>
  <StateOnLists>
   <StateOnList>
    <Email>john@yahoo.com</Email>
    <ListId>123</ListId>
    <Name>Testowa Lista</Name>
    <Status>Unsubscribed</Status>
    <SubscribedOn>2014-12-29T15:30:09</SubscribedOn>
   </StateOnList>
   <StateOnList>
    <Email>john@yahoo.com</Email>
    <ListId>456</ListId>
    <Name>Testowa Seed Lista 1 (3)</Name>
    <Status>Active</Status>
    <SubscribedOn>2014-11-12T12:30:41</SubscribedOn>
   </StateOnList>
   <StateOnList>
    <Phone>48789456123</Phone>
    <ListId>789</ListId>
    <Name>Testowa Lista 2</Name>
    <Status>Active</Status>
    <SubscribedOn>2015-01-11T11:00:02</SubscribedOn>
   </StateOnList>
   </StateOnLists>
   <SuppressionLists>
   <SuppressionList>
    <Id>1</Id>
    <Name>testowa lista suppression nr 1</Name>
    <Type>Phone<
   </SuppressionList>
   <SuppressionList>
    <Id>2</Id>
    <Name>testowa lista suppression nr 2</Name>
   </SuppressionList>
   </SuppressionLists>
   <Id>3045574</Id>
   <Email>john@yahoo.com</Email>
   <Phone>48789456123</Phone>
   <CustomSubscriberId>522145698</CustomSubscriberId>
   <Firstname>John</Firstname>
   <Lastname>Doe</Lastname>
   <Vendor>RIVER2</Vendor>
   <Ip>90.2.214.146</Ip>
   <Properties>
    <Property>
    <Id>1</Id>
    <Source>NotSet</Source>
    <DateTimeValue xsi:type=”xsd:dateTime”>2016-07-19T00:00:00</DateTimeValue>
    <Type>Datetime</Type>
    <FriendlyName>Date added</FriendlyName>
    <Description/>
    <Name>dateadded</Name>
   </Property>
   <Property>
    <Id>5</Id>
    <Source>NotSet</Source>
    <StringValue xsi:type=”xsd:string”>Mr</StringValue>
    <Type>Text</Type>
    <FriendlyName>Title</FriendlyName>
    <Description/>
    <Name>title</Name>
   </Property>
  </Properties>
 </Data>
</ApiResponse>
获取收件人任务历史:
请求
GET https://api.esv2.com/v2/Api/Subscribers?apiKey=test_api_key1&email=john%40yahoo.com&option=EventsHistory HTTP/1.1

Accept-Encoding: gzip,deflate
Host: api.esv2.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

应答

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=2baf0f58-63a5-44bc-9673-988be8061978; path=/
X-Powered-By: ASP.NET
Date: Tue, 27 Jan 2017 13:37:40 GMT
Content-Length: 1259

<ApiResponse xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”>
 <Data>
  <Events>
   <Event>
    <StartDate>2015-01-25T10:00:00</StartDate>
    <EndDate>2015-01-25T11:00:00</EndDate>
    <Channel>Email</Email>
    <MessageType>Newsletter</MessageType>
    <EventType>Click</EventType>
    <EventCount>1</EventCount>
    <MessageId>120540</MessageId>
    <MessageSubject>test of links</MessageSubject>
   </Event>
   <Event>
    <StartDate>2015-01-25T10:00:00</StartDate>
    <EndDate>2015-01-25T11:00:00</EndDate>
    <Channel>SmsMms</Email>
    <MessageType>Newsletter</MessageType>
    <EventType>Send</EventType>
    <EventCount>1</EventCount>
    <MessageId>473821</MessageId>
    <MessageSubject>test competition announcement</MessageSubject>
   </Event>
   <Event>
    <StartDate>2015-01-25T08:00:00</StartDate>
    <EndDate>2015-01-25T09:00:00</EndDate>
    <Channel>Email</Email>
    <MessageType>Newsletter</MessageType>
    <EventType>Send</EventType>
    <EventCount>1</EventCount>
    <MessageId>120540</MessageId>
    <MessageSubject>test of links</MessageSubject>
   </Event>
  </Events>
 </Data>
</ApiResponse>