添加收件人

Add subscriber 添加收件人

Subscribers(收件人) 相关接口允许使用HTTP POST方式添加新的收件人。如果您要添加的收件人已经存在（收件人有唯一指定的Email地址或者电话号码），则它将被更新

可在一个请求里添加一个或多个收件人

请注意不能通过一条API请求添加或者更新超过100个收件人

请求格式

ApiRequest子元素:
元素/属性 类型 描述
ApiKey string API key, 身份验证.
ReturnData boolean 如设为 “true” (注意小写!)，针对每个添加的收件人都会有附加信息作为返回值. 对于MultiData 非常有用
VerboseErrors boolean 如设为 “true” (注意小写!)，报错信息会以冗长的方式出现在返回值. 见示例
Data complex 对象包括单个收件人数据. 与MultiData必选其一填写
MultiData complex 对象包括多个收件人数据，以完成一批收件人的添加. 与Data必选其一填写

请求数据格式

Data子元素:
元素/属性 类型 描述
xsi:type – 描述操作数据的类型. 在此请求中应恒为 “Subscriber”
Mode string 添加模式. 在下个表格中查看支持的模式
选填. 默认为 “AddAndUpdate”
Force boolean 如设为 “true” (注意小写!)，这个参数将导致发送另一个确认邮件给收件人. 只应用于双重选择加入的收件人列表中和还未确认的收件人. 选填. 默认为 “false”.
ListId integer 收件人所加入的列表标识ID，必填.
AllowUnsubscribed boolean 如果设置为”false” (注意小写!), 系统不会添加已退订的收件人. 默认为”true”
AllowRemoved boolean 如果设置为”false” (注意小写!), 系统不会添加后台已删除收件人. 默认为”true”
MatchingMode string Email, 收件人匹配码. 此字段为收件人主要标识. 选填. 可选值: Email地址, 收件人标识ID, ID, 电话号码.

只上传收件人Email地址时默认为Email地址

只上传收件人电话号码时默认为电话号码

只上传收件人ID时默认为收件人ID
Id integer 收件人唯一标识ID. 如需改变订阅用户email地址请留意此项. 选填.
Email string 收件人Email. 选填.
EmailMd5 string 收件人Email的MD5格式. 选填.
Phone string 收件人电话号码 (开通短信/彩信业务). 选填. ** 见下注解
CustomSubscriberId string Subscriber’s custom ID. Optional.
Firstname string 收件人的名. 选填.
Lastname string 收件人的姓. 选填.
TrackingCode string 收件人来源标识 (例如，网页上的特定表单). 选填.
Name string 全名. 可应用于无单独的姓与名两个数据的情况. 会以“Firstname Lastname”模板匹配.
Vendor string 收件人的访问来源名称/标识ID. 选填.
Ip string 收件人上次行为/任务的IP地址. 选填.
Properties complex 自定义属性字段集合 (属性字段Property子元素). 选填.
SpamDecoy string 甄别填写网页表单时Spam Bots的特殊字段. 如果你发送你的网站有spam bot, 可以填写这个spam字段, 它将日后用于报告分析.
注意! 如果这个字段被填写, 收件人不会被添加到后台. 只会被记录和返回适当的错误代码. 如果你想要添加收件人到平台，请不要填写这个字段
*请注意添加新的收件人必须提供Email地址. 更新一个指定收件人需要提供Email地址或者Email的MD5格式. 改变一个收件人Email地址需要提供Email地址还有收件人ID字段.
**开通短信/彩信服务后可选添加Email地址或者电话号码 (如更新一个指定收件人需要提供Email地址, Email的MD5格式, 电话号码中的一个. 如更新Email地址或者电话号码则需要提供Email地址, Email的MD5格式, 电话号码, ID，收件人标识ID及改变后的Email地址或者电话号码)
注意! 每个电话号码需要包含国家前缀, 并且长度不超过20个字符
以下是有效输入值及在系统中存储的方式:
+48501228855 = 48501228855
(+48)501228855 = 48501228855
+48 (501) 228855 = 48501228855
0048 501 22 88 55 = 48501228855

支持的添加模式：

模式 动作
AddAndUpdate 添加新的收件人并更新列表中现有收件人的某些属性字段
AddAndReplace 添加新的收件人并替换列表中现有收件人的某些属性字段 (注意: 如果新数据中现有收件人的某些属性值为空，将会擦除原值)
AddAndIgnore 添加新的收件人但不更新或替换列表中现有的收件人的任何属性字段
IgnoreAndUpdate 不添加新的收件人，仅更新列表中现有的收件人的某些属性字段
IgnoreAndReplace 不添加新的收件人，仅替换列表中现有的收件人的某些属性字段 (注意: 如果新数据中现有收件人的某些属性值为空，将会擦除原值)
Property子元素:
元素/属性 类型 描述
Id integer 预定义的收件人属性字段标识. 必填
Value mixed 属性字段值. 必填.类型取决于xsi:type (必填). 数据类型应与预定义属性字段类型保持一致.*

*xsi:type应与属性字段类型保持一致，提供不正确的数据类型会导致错误产生，详细内容见下表

属性字段类型 允许的xsi:type 范例数据
Text xs:string this is a test, foobar
Number xs:integer 12345
Money xs:decimal, xs:integer 123.45, 123
Date xs:date 1985-03-12
Datetime xs:dateTime, xs:date 1985-03-12T12:00:00
Boolean xs:boolean true, false, 1, 0
Url xs:string http://www.domain.com/page.html
SingleSelect xs:string value1, value2, M, F*

*每个单选属性只接受一个预定义值.

添加多个订阅用户，用MultiData元素代替Data元素:

元素/属性 类型 描述
MultiData complex 请求添加新收件人时，与Data元素添加单个收件人具有相同结构

注意：使用MultiData，如果有报错信息，则可能会以冗长的方式出现在返回值. 见以下示例.

应答格式

通常情况下，该请求将不返回任何数据值。如果成功，返回值将是HTTP 代码 “201 Created”。 我们可以调整该行为，利用两个标记：ReturnData 以及 VerboseErrors.
ReturnData 如被应用，则每个成功添加的收件人都会返回附加信息。
VerboseErrors  如被应用，则会改变所返回的报错信息的形式（如果有报错信息的话).
错误应答当VerboseErrors=true:
ApiResponse子元素:
元素/属性 类型 描述
ErrorMessage complex 对象含有报错信息.
ErrorMessage子元素:
元素/属性 类型 描述
Code integer Error code, 如 “400”.
Messages complex 报错信息列表.
Messages子元素:
元素/属性 类型 描述
Message complex 对象含有报错信息
Message子元素:
元素/属性 类型 描述
for string 后接报错信息所对应的收件人Email. XML 属性.
(content) string 报错信息. XML中的元素内容值.
OK应答当ReturnData=true:
ApiResponse子元素:
元素/属性 类型 描述
Data complex SubscriberData元素组成的数组数据
Data子元素:
元素/属性 类型 描述
SubscriberData complex 对象含有单个收件人的信息.
SubscriberData子元素:
元素/属性 类型 描述
Email string 收件人Email
Id integer 收件人ID – 只有收件人被添加或已存在于列表中时被返回
Phone string 收件人电话号码. 当单元存在短信/彩信业务时返回.
CustomSubscriberId string 收件人标识ID. 只有存在时返回.
WasAdded boolean 该标记意味着收件人被添加到了列表
WasIgnored boolean 该标记意味着收件人被跳过 (取决于添加模式, 如 AddAndIgnore 模式 将跳过已经存在于列表的收件人).

示例

请求（创建单个订阅用户):
POST https://api.esv2.com/v2/Api/Subscribers/ HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: text/xml 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 715 
 
 
 <ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
    <ApiKey>test_api_key1</ApiKey>
    <Data xsi:type=”Subscriber”>
       <Mode>AddAndUpdate</Mode>
       <Force>true</Force>
       <ListId>1</ListId>
       <Email>john.smith@domain.com</Email>
       <Firstname>John</Firstname>
       <Lastname>Smith</Lastname>
       <TrackingCode>123</TrackingCode>
       <Vendor>xyz</Vendor>
       <Ip>11.22.33.44</Ip>
       <Properties>
          <Property>
             <Id>2</Id>
             <Value xsi:type=”xs:string”>student</Value>
          </Property>
          <Property>
             <Id>3</Id>
             <Value xsi:type=”xs:dateTime”>1985-03-12</Value>
          </Property>
       </Properties>
    </Data>
 </ApiRequest>
请求（创建多个订阅用户):
<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>test_api_key1</ApiKey>
   <MultiData>
     <Subscriber>
        <Mode>AddAndUpdate</Mode>
        <Force>true</Force>
        <ListId>1</ListId>
        <Email>john.smith@domain.com</Email>
        <Firstname>John</Firstname>
        <Lastname>Smith</Lastname>
        <TrackingCode>123</TrackingCode>
        <Vendor>xyz</Vendor>
        <Ip>11.22.33.44</Ip>
     </Subscriber>
     <Subscriber>
        <Mode>AddAndUpdate</Mode>
        <Force>true</Force>
        <ListId>1</ListId>
        <Email>jane.doe@domain.com</Email>
        <Firstname>Jane</Firstname>
        <Lastname>Doe</Lastname>
        <TrackingCode>456</TrackingCode>
        <Vendor>abc</Vendor>
        <Ip>22.33.44.55</Ip>
     </Subscriber>
   </MultiData>
</ApiRequest>
OK应答:
HTTP/1.1 201 Created
Cache-Control: private
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Wed, 28 Oct 2009 15:35:17 GMT
Content-Length: 0
错误应答:
HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 1.0
X-AspNet-Version: 2.0.50727
X-Powered-By: ASP.NET
Date: Wed, 28 Oct 2009 11:32:07 GMT
Content-Length: 239

<ApiResponse xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
<ErrorMessage>
<Code>400</Code>
<Message>Email is invalid;</Message>
</ErrorMessage>
</ApiResponse>
请求 (添加多个收件人verbose冗长报错信息标记被应用)：
 

POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Content-Length: 513
Host: localapi2-dev
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
 
<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>test_api_key1</ApiKey>
   <VerboseErrors>true</VerboseErrors>
   <MultiData>
     <Subscriber>
        <Mode>AddAndUpdate</Mode>
        <ListId>1</ListId>
        <Email>john.smith@@domain.com</Email>
     </Subscriber>
     <Subscriber>
        <Mode>AddAndUpdate</Mode>
        <ListId>1</ListId>
        <Email>jane.doe@domain.com</Email>
     </Subscriber>
   </MultiData>
</ApiRequest>
报错应答(verbose冗长报错信息标记被应用)：
HTTP/1.1 400 Bad RequestCache-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=6df3c82d-189c-4984-b8b2-a5d78bde501d; path=/
X-Powered-By: ASP.NET
Date: Wed, 29 Jul 2015 11:00:50 GMT
Content-Length: 373

<ApiResponse xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
<ErrorMessage>
<Code>400</Code>
<Messages>
<Message for=”john.smith@@domain.com”>Email is invalid</Message>
<Message for=”jane.doe@domain.com”>Address is present on your blacklist</Message>
</Messages>
</ErrorMessage>
</ApiResponse>
请求 (添加多个收件人ReturnData标记被应用):
POST https://api.esv2.com/v2/Api/Subscribers HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml
Content-Length: 558
Host: localapi2-dev
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>test_api_key1</ApiKey>
   <VerboseErrors>true</VerboseErrors>
   <ReturnData>true</ReturnData>
   <MultiData>
     <Subscriber>
        <Mode>AddAndUpdate</Mode>
        <ListId>1</ListId>
        <Email>john.smith@domain2.com</Email>
     </Subscriber>
     <Subscriber>
        <Mode>AddAndUpdate</Mode>
        <ListId>1</ListId>
        <Email>jane.doe@domain2.com</Email>
     </Subscriber>
   </MultiData>
</ApiRequest>
OK应答 (添加多个收件人ReturnData标记被应用):
HTTP/1.1 201 Created
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=09987c87-b886-4164-8fad-89d6ab3ef6bb; path=/
X-Powered-By: ASP.NET
Date: Wed, 29 Jul 2015 11:50:48 GMT
Content-Length: 517

<ApiResponse xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”>
 <Data>
  <SubscriberData>
   <Email>john.smith@domain2.com</Email>
   <Id>4238647</Id>
   <WasAdded>true</WasAdded>
   <WasIgnored>false</WasIgnored>
  </SubscriberData>
  <SubscriberData>
   <Email>jane.doe@domain2.com</Email>
   <Id>4238648</Id>
   <WasAdded>true</WasAdded>
   <WasIgnored>false</WasIgnored>
  </SubscriberData>
 </Data>
</ApiResponse>