创建事务性邮件

Create transactional message 创建事务性邮件

创建一个事务性邮件，邮件正文可以在储存在请求中或来自于外源数据（如：FTP服务器）).

请求数据格式

创建一封新的事务性邮件模板所需的数据如下.

Data子元素:

元素/属性名称 类型 描述
Content complex 邮件内容，必填.
SuppressionLists array[integer] SuppressionList元素组成的数组包含了投递过程中所要应用的禁止列表ID，选填.
Channels array[complex] 发送通道及权重设置. 如忽略, 会使用默认发送设置.
Status string 事务性邮件的状态。有效值：Active,Inactive。默认值为Active,即创建后立即启用。选填.

 

Content子元素:

元素/属性名称 类型 描述
FromName string 邮件中的“发送方名称:”, 必填.
FromEmail string 邮件中的“发送方地址:” ，必填.
ReplyToName string 邮件中的“回复方名称:”, 选填.
ReplyToEmail string 邮件中的“回复方地址:”, 选填.
Subject string 事务性邮件标题.必填.
Html string 邮件包含的HTML内容. 为了XML的字符转义完整，HTML内容应封装在CDATA节点中，请查看示例。选填.*
Plain string 事务性邮件的纯文本内容，选填.*
AmpHtml string AMP HTML邮件内容. 为了XML的字符转义完整，HTML内容应封装在CDATA节点中，请查看示例。选填.*
Header integer 采用页眉模板ID. 选填.
Footer integer 采用页脚模板ID. 选填.
ContentFromUrl complex 若HTML内容不存在于XML语言格式的请求中，则需从外源下载时使用。选填.*
GoogleAnalyticsTags complex Google Analytics 标签布置于事务邮件模板内容中的链接. 选填. 如果省略, Google Analytics将不会在此事务邮件中启用.
Tags array[string] 为方便起见，用于标示事务邮件模板的标签，选填.
Attachments complex 附件Attachment元素的集合，包含附加的附件数据（例如，随newsletter一起发送的加密PDF文件），选填.**
UrlIntegrations complex 在单元设置中创建的URL集成列表ID.可选.
EnableClickTrack boolean 如果设置为“false”，那么不会统计该邮件的点击率。默认为“true”。选填. 
EnableOpenTrack boolean 如果设置为“false”，那么不会统计该邮件的打开率。默认为“true”。选填. 

* 你可以用Html、Plain元素或者AMPHtml，将电邮内容内置，或是通过使用ContentFromUrl元素指定内容将从特定外源下载（如网页或FTP服务器中包含HTML和图片的zip文件）。如果这两个地方（内置和外源）都没有找到内容，会返回报错信息.如果有多个Html，Plain和/或AmpHtml文件，则使用最后一个文件作为内容。如果您选择使用AMPHtml，您应同时准备Html或Plain版本进行邮件备份
AMPHtml内容必须包含全部需要的元素（请参阅示例），所有链接必须是安全链接（如https://）

** 不可能同时应用ContentFromUrl和Attachments元素.

Note: If you wish to send inline images within your transactional, using ContentFromUrl method is the only way to do it.

ContentFromUrl子元素:

元素/属性名称 类型 描述
Url string 导入文件的URL地址. 支持协议为 HTTP, HTTPS, FTP, FTPS 以及 SFTP. 如 ftp://www.domain.com/mycreative.zip
Username string 用于远程验证身份的用户名，选填.
Password string 用于远程验证身份的密码，选填.
FtpAuth string FTP服务器的身份认证方式，选填，有效值为:

    • None – FTP 服务器不支持安全认证（身份认证） (默认).
    • ExplicitTls – Explicit TLS/SSL 认证
    • ExplicitSsl – 仅Explicit SSL 认证
    • ImplicitSsl – Implicit SSL 认证
FtpUseActiveMode boolean 如果设为 “true”, 主动方式将被应用于FTP连接。默认为 “false” – 被动式FTP连接将被应用.

 

GoogleAnalyticsTags子元素:

元素/属性名称 类型 描述
Campaign string Google Analytics 标签 “utm_campaign”.选填.
Source string Google Analytics 标签 “utm_source”. 选填.
Content string Google Analytics 标签 “utm_content”. 选填.

注意：剩下的标签“utm_medium”被默认为“Email”.

 

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

URLintegration子元素:

元素/属性名称 类型 描述
Id int URL集成列表(必须存在,删除过的无效).必填.
 

Channel子元素:

元素/属性名称 类型 描述
Ip string 发送通道IP地址.
Percentage integer 通过此通道投递的邮件数量百分比（%）.*

*所有所选通道的百分比值之和必须为100%，否则就会产生报错信息。比如，配置可以为2通道配比30/70或是三通道25/25/50，可用的IP通道列表可以在ExpertSender后台中的业务单元设置（unit settings）里找到.

应答

该接口会返回所创建事务邮件模板的ID。ID可以通过检索邮件状态数据（见Api/ MessageStatistics）确定事务邮件的具体进程.

应答数据元素:

元素/属性名称 类型 描述
(Data element content) int 所创建事务邮件的ID.

 

示例

创建一封事务性邮件

请求:
POST https://api.esv2.com/v2/Api/TransactionalsCreate HTTP/1.1 

Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 1727 
 
 
 <ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>test_api_key</ApiKey>
   <Data>
     <Content>
       <FromName>test</FromName>
       <FromEmail>test@test.com</FromEmail>
       <Subject>Hello!</Subject>
       <Html><![CDATA[HelloWorld!<br/>${Snippet(‘name’)}<br/>${Snippet(‘age’)}<br/>]]></Html>
     </Content>
     <Status>Active</Status>
   </Data>
应答:
HTTP/1.1 201 Created
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.5
X-AspNetMvc-Version: 3.0
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
Date: Tue, 27 Mar 2012 13:28:01 GMT
Content-Length: 149<ApiResponse xmlns:xsd=”http://www.w3.org/2001/XMLSchema” xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance”>
 <Data>1498</Data>
</ApiResponse>

全参数配置下创建一封从外源抓取内容的事务性邮件

请求:
POST https://api.esv2.com/v2/Api/TransactionalsCreate HTTP/1.1 

Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 1727 
 <ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>test_api_key</ApiKey>
   <Data>
     <SuppressionLists>
       <SuppressionList>77</SuppressionList>
     </SuppressionLists>
     <Content>
       <FromName>test</FromName>
       <FromEmail>test@test.com</FromEmail>
       <ReplyToName>test2</ReplyToName>
       <ReplyToEmail>test2@test.pl</ReplyToEmail>
       <Subject>Hello!</Subject>
       <ContentFromUrl>
         <Url>ftp://ftp.domain.com.creative.zip</Url>
         <Username>username</Username>
         <Password>password</Password>
         <FtpAuth>ExplicitTls</FtpAuth>
       </ContentFromUrl>
       <GoogleAnalyticsTags>
         <Campaign>testcampaign</Campaign>
         <Source>testsource</Source>
         <Content>testcontent</Content>
       </GoogleAnalyticsTags>
       <UrlIntegrations>
         <UrlIntegration>
            <Id>30</Id>
         </UrlIntegration>
         <UrlIntegration>
             <Id>32</Id>
         </UrlIntegration>
       </UrlIntegrations>
       <Tags>
         <Tag>tag1</Tag>
         <Tag>tag2</Tag>
       </Tags>
       <EnableClickTrack>true</EnableClickTrack>
       <EnableOpenTrack>true</EnableOpenTrack>
     </Content>
     <Channels>
       <Channel>
         <Ip>192.168.10.22</Ip>
         <Percentage>30</Percentage>
       </Channel>
       <Channel>
         <Ip>192.168.10.3</Ip>
         <Percentage>70</Percentage>
       </Channel>
     </Channels>
     <Status>Active</Status>
   </Data>
 </ApiRequest>

创建一封带附件的事务性邮件

POST https://api.esv2.com/v2/Api/TransactionalsCreate HTTP/1.1 

Accept-Encoding: gzip,deflate 
Content-Type: text/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 32566
<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>test_api_key1</ApiKey>
   <Data>
     <Content>
       <FromName>test</FromName>
       <FromEmail>test@test.com</FromEmail>
       <Subject>Hello!</Subject>
       <Plain>Hello friend, how are you?</Plain>
       <Attachments>
        <Attachment>
        <FileName>test.pdf</FileName>
        <MimeType>application/pdf</MimeType>  <Content>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
…
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G</Content>
      </Attachment>
    </Attachments>
     </Content>
   </Data>
 </ApiRequest>
注：由于附件内容过长，部分内容以“……”代替.

发送AMP Html的事务性邮件

POST https://api.esv2.com/v2/Api/TransactionalsCreate HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
User-Agent: Jakarta Commons-HttpClient/3.1
Host: api.esv2.com
Content-Length: 1727

<ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema“>
    <ApiKey>test_api_key</ApiKey>
    <Data>
        <SuppressionLists>
            <SuppressionList>77</SuppressionList>
        </SuppressionLists>
        <Content>
            <FromEmail>test@test.com</FromEmail>
            <Subject>Hello!</Subject>
                <Html>Some fallback HTML code here</Html>
            <AmpHtml><![CDATA[
            <!doctype html>
            <html amp4email>
            <head>
                <meta charset=”utf-8″>
                <script async src=”https://cdn.ampproject.org/v0.js“></script>
                <style amp4email-boilerplate>body{visibility:hidden}</style>
            </head>
            <body>
                Hello, AMP world.

                Please use AMP markup if there is such like “amp-img” instead of “img”

                <amp-img src=”https://sites.google.com/site/expertsenderapiv2/_/rsrc/1530873497175/config/Es-                    API.png.1530873496983.png”
                    alt=”Welcome”
                    width=”906″
                    height=”132″>
                </amp-img>
            </body>
            </html>
            ]]></AmpHtml>
        </Content>
        <Channels>
            <Channel>
                <Ip>192.168.10.22</Ip>
                <Percentage>30</Percentage>
            </Channel>
            <Channel>
                <Ip>192.168.10.3</Ip>
                <Percentage>70</Percentage>
            </Channel>
        </Channels>
        <Status>Active</Status>
    </Data>
</ApiRequest>