发送系统事务性邮件

Send Syetem Transactional messages
发送系统事务性邮件

Transactionals接口通过HTTP POST方法允许向单一收件人发送之前创建的事务类邮件。事务类邮件通过必须的ID参数指定。

如果该事务性邮件的收件人已经存在于收件人列表（收件人邮件地址或手机号码唯一）, 将会更新他的相关参数信息. 如果收件人不存在于任何收件人列表，他的邮件地址或手机号码将会被添加至收件人列表.

当发送事务性邮件时，只有全局黑名单可以对单个的收件人抑制其发送. 检查收件人是否存在于本地黑名单这一步将被略过. 

请求数据格式

请求URL参数:
参数 类型 描述
ID integer Transactional message ID. Required as a part of address (not GET parameter). See example below.
示例URL:
https://api.esv2.com/v2/Api/SystemTransactionals/123
向单一收件人发送事务邮件请求中的Data元素部分.

Data子元素: 

元素/属性名称 类型 描述
ReturnGuid boolean 如果设置为true，请求的返回值XML中将包含所发送的事务邮件的“全域唯一标示符”GUID(globally unique identifier). 选填.默认为false.
Receiver complex 描述将会收到该事务邮件的收件人.
Snippets complex “Snippet” 元素集, 描述嵌入邮件主体/标题等的HTML 代码片段，选填.
Attachments complex “Attachment”元素集,包括额外附加数据 (如与事务邮件同时发送的编码PDF文件). 选填.


Receiver子元素: 

元素/属性名称 类型 描述
Id integer 收件人标识ID. 选填.*
Email string 收件人email. 选填.*
EmailMd5 string 收件人email的Md5 hash值. 选填.*
Firstname string 收件人名称. 选填.
Lastname string 收件人姓名. 选填.
TrackingCode string 收件人追踪识别符 (例如，比较特殊的Web端页面表单). 选填.
Name string 收件人全名. 在性别和名称无法分开时使用. 默认会按照“名称+姓名”的方式组合而成.
Vendor string 收件人来源信息. 选填.
Ip string 收件人IP地址. 选填.
Properties string 收件人自定义属性段集合 (属性元素). 选填. 详情见 添加收件人 页面的

* 注意:  Id/Email/EmailMd5中必须选其一来确定收件人. 如果使用Email/EmailMd5 来鉴别收件人, 其收件人邮箱或MD5值必须存在于收件人列表中. ID在所有参数中优先级最高.

Snippet子元素: 

元素/属性名称 类型 描述
Name string 片段Snippet名.*
Value string 片段Snippet片段值.**

* 注意：片段Snippet名所对应的个性化标签可以用于邮件内容，标题或邮件其他部分中.

示例：如果片段Snippet名是 mySnippet，其值会可以替换个性化标签${Snippet(‘mySnippet’)}。

**注意：片段Snippet可以包括HTML标记（若附于CDATA部分-见示例请求）和个性化标签（如*[subscriber_firstname]*）。动态内容DC在片段Snippet中并不起作用

. 

Attachment子元素:
元素/属性名称 类型 描述
FileName string 附件文件名.如 “infosheet.pdf”. 应为唯一的名字（任何两个附件都不应该重名）. 必填.
MimeType string MIME 标准规定的文件类型. 如 “application/pdf”. 如忽略，则默认的 MIME 类型将被应用: “application/octet-stream”. 选填. MIME 类型会影响该Email的附件在各个不同的邮件接收客户端中将被如何处理。所以建议始终明确指定附件的正确文件类型.*
Content string 附件内容. 必须是Base64 编码.** 见示例请求. 必填.

*注意： MIME 文件类型的指定请见:http://en.wikipedia.org/wiki/Internet_media_type

** 注意：二进制信息变为Base64编码在大多数编程语言中都可用，更多关于Base64编码请见: http://en.wikipedia.org/wiki/Base64
警告: 如果试图用已暂停或已删除的事务性邮件模板发送系统事务性邮件会报错.

 

应答

 
该接口默认返回值为空，以及HTTP状态码”201 – Created”. 但你可以要求应答返回GUID值，这时就会收到包含GUID值的XML应答文件.
 

Response子元素: 

元素/属性名称 类型 描述
(Data element content) string 发送事务邮件的“全域唯一标示符”GUID (globally unique identifier).
 

示例

包含两个片段Snippet，用收件人邮件地址的请求:
POST https://api.esv2.com/v2/Api/SystemTransactionals/123 HTTP/1.1 

Accept-Encoding: gzip,deflate 
Content-Type: application/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 585 
<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
  <ApiKey>test_api_key1</ApiKey>
  <Data>
    <Receiver>
      <Email>patrick@mydomain.com</Email>
    </Receiver>
    <Snippets>
      <Snippet>
        <Name>helloMessage</Name>
        <Value><![CDATA[ <b>Hello Patrick!<-b> ]]></Value>
      </Snippet>
      <Snippet>
        <Name>pointsNumber</Name>
        <Value>2076</Value>
      </Snippet>
    </Snippets>
  </Data>
</ApiRequest>

 

不包含片段Snippet，使用收件人识别ID的请求:
POST https://api.esv2.com/v2/Api/SystemTransactionals/1593 HTTP/1.1 

Accept-Encoding: gzip,deflate 
Content-Type: application/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 241 
<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
  <ApiKey>test_api_key1</ApiKey>
  <Data>
    <Receiver>
      <Id>12345</Id>
    </Receiver>
  </Data>
</ApiRequest>

 

包含附件的请求:
POST http://api.esv2.com/v2/Api/SystemTransactionals/2449 HTTP/1.1

Accept-Encoding: gzip,deflate
Content-Type: application/xml;charset=UTF-8
Content-Length: 113056
Host: api.esv2.com
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>
   <Data>
      <Receiver>
         <Email>patrick@mydomain.com</Email>
      </Receiver>
      <Attachments>
        <Attachment>
        <FileName>test.pdf</FileName>
        <MimeType>application/pdf</MimeType>
        <Content>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
…
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G</Content>
      </Attachment>
    </Attachments>
  </Data>
</ApiRequest>
Note: Part of long attachment content was cut and “…” was inserted.

 

要求返回GUID的请求:
POST https://api.esv2.com/v2/Api/SystemTransactionals/2449 HTTP/1.1

Accept-Encoding: gzip,deflate
Content-Type: application/xml;charset=UTF-8
Content-Length: 317
Host: api.esv2.com
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>
     <Data>
         <ReturnGuid>true</ReturnGuid>
         <Receiver>
             <Email>patrick@mydomain.com</Email>
         </Receiver>
    </Data>
 </ApiRequest>

 

OK 应答(不含GUID):
HTTP/1.1 201 Created
Cache-Control: private
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: Fri, 08 Jul 2011 11:34:53 GMT
Content-Length: 0

 

OK 应答(包含GUID):
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=72940603-7e6e-4e32-8dcf-85b547297551; path=/
X-Powered-By: ASP.NET
Date: Wed, 28 Jan 2015 16:30:11 GMT
Content-Length: 181<ApiResponse xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”>
 <Data>c3a4bda9-07be-4d48-af20-df51293ec78f</Data>
</ApiResponse>

 

错误应答 (用户处于黑名单中):
HTTP/1.1 400 Bad Request
Cache-Control: private
Content-Type: text/xml; 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: Fri, 08 Jul 2011 11:37:19 GMT
Content-Length: 274<ApiResponse xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xsd=”http://www.w3.org/2001/XMLSchema”>
 <ErrorMessage>
  <Code>400</Code>
  <Message>Subscriber is blacklisted.</Message>
 </ErrorMessage>
</ApiResponse>