发送事务性邮件

Send Transactional messages 发送事务性邮件

Transactionals接口通过HTTP POST方法允许向单一收件人发送之前创建的事务类邮件。事务类邮件通过必须的ID参数指定。目前，这是Transactionals 相关集合唯一有效的接口.

请求数据格式

请求URL参数:
参数 类型 描述
ID integer 事务邮件ID.作为地址的一部分应用（不是GET参数）.见以下示例..
示例URL:
https://api.esv2.com/v2/Api/Transactionals/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值. 选填.*
ListId integer 收件人所在列表标识ID. 可用来指定常用来发送事务邮件的列表。如果当前收件人存在于多个列表中也会有帮助。如忽略, 第一个找到收件人的列表会被用来作为收件人所在列表对待.选填.

* 注意：为了指定收件人，ID/Email/EmailMd5元素必须填写其一。如果Email/EmailMd5已填写，那有这个email或有该email的Md5值的收件人必须存在于后台数据库。如果两个字段都被填写了，ID优先作用.

 

Snippet子元素:

元素/属性名称 类型 描述
Name string Snippet name.*
Value string Snippet value.**

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

示例：如果片段Snippet名是 mySnippet, 其值会可以替换个性化标签 *[tr_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” 被返回。但是，你可以设置元素ReturnGuid使得请求的返回值XML中将包含所发送的事务邮件的“全域唯一标示符” GUID.
 

Response子元素: 

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

示例

请求中含有两个片段Snippet，收件人通过email指定:
POST https://api.esv2.com/v2/Api/Transactionals/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/Transactionals/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>

 

请求中有附件Attachment元素:
POST http://api.esv2.com/v2/Api/Transactionals/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>
注意：附件内容过长所以此处的一部分用“…”代替.

 

请求中有ReturnGuid元素设置:
POST https://api.esv2.com/v2/Api/Transactionals/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 does not exist in the database or has unsubscribed.</Message>
</ErrorMessage>
</ApiResponse>