创建及发送Newsletter

Create and send newsletter
创建及发送Newsletter

Newsletter接口可以用来创建及发送Newsletter。内容可以与请求一并发送或是存储于外源（如，FTP服务器）.

请求数据格式

创建Newsletter请求中的Data元素部分.

Data子元素:

元素/属性名称 类型 描述
Recipients complex Newsletter目标收件人信息，必填.
Content complex 邮件内容，必填.
DeliverySettings complex 发送设置 (发送日期，通道等). 选填. 如忽略, 会使用默认发送设置.


Recipients子元素:

元素/属性名称 类型 描述
SubscriberLists array[integer] SubscriberLists元素组成的数组包含了Newsletter的目标收件人列表ID，选填.*
SubscriberSegments array[integer] SubscriberSegment元素组成的数组包含了Newsletter目标收件人细分ID，选填.*
SeedLists array[integer] SeedLists元素组成的数组包含了投递过程中所要发送的目标测试列表ID，选填.*
SuppressionLists array[integer] SuppressionLists元素组成的数组包含了投递过程中所要应用的禁止列表ID，选填.

* Newsletter需至少选定一个收件人列表，收件人细分或测试列表.  空的目标收件人集合会导致报错信息.


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 标签布置于Newsletter内容中的链接. 选填. 如果省略, Google Analytics将不会在此Newsletter启用.
Tags array[string] 为方便起见，用于标示Newsletter的标签，选填.
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元素.

注意：如果想发送包含本地图片的Newsletter，那么用ContentFromUrl元素是唯一方法.

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

 

DeliverySettings 子元素:

 

元素/属性名称 类型 描述
DeliveryDate dateTime Newsletter发送日期. 选填. 若是默认，Newsletter会直接发送.
TimeZone string 发送时间中所应用的时区.选填. 默认为标准（业务单元设置中）时区设置. 合理的取值.
OverrideDeliveryCap boolean 如设为 “true”, Newsletter会自动忽略邮件发送频率上限帽设置。选填. 默认为 “false”.
ThrottlingMethod string 邮件发送控制阀方式，见下方不同控制阀方式的介绍. 选填. 默认为 “None” (请务必修改为Auto).
ManualThrottlingTime int 手动控制邮件发送数量控制阀的时间长度（小时为单位）。如果ThrottlingMethod 设定为“Manual”，就需要进行此项设置，其他情况则忽略.
TimeOptimizationPeriod string 发送时间优化时间设置 (STO). 这个设置只适用于开启了“发送时间优化”的情况. 有效值包括： “24h” (24 小时 – 默认选项) 和 “7d” (7 天).
Channels array[complex] Channels元素组成的数组描述的发送通道. 选填. 如忽略, 标准（业务单元设置中）IP通道设置会被用于发送此Newsletter.

邮件发送控制阀方式:

名称 动作
None (禁用) 不启用邮件发送控制阀.Newsletter会被以最快速度发送出. 这是默认方式, 但不推荐使用.
Auto 自动邮件发送控制阀.基于收件人数量及业务单元中的设置自动计算发送时间.
Manual 手动邮件发送控制阀.  以小时为单位，手动设置完整发送完邮件所要用的时间.
TimeOptimized 发送时间优化 (STO). 发送时间将根据之前每个收件人的表现而被计算出，优化的范畴可以选择24小时或1星期.
TimeTravel 时区自适应. 发送时间会根据每个收件人所在的时区而分别被计算出.



Channel 子元素:

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

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

URLintegration 子元素:

 

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

示例:


<UrlIntegrations>
<UrlIntegration>
<Id>30</Id>
</UrlIntegration>
<UrlIntegration>
<Id>32</Id>
</UrlIntegration>
</UrlIntegrations>

 

应答

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

Response子元素:

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

 

示例

发送一封简单的newsletter

请求:
POST https://api.esv2.com/v2/Api/Newsletters 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: 457 
 
 
 <ApiRequest xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance” xmlns:xs=”http://www.w3.org/2001/XMLSchema”>
   <ApiKey>2OAEcpz0Rwv3Mhc9nTQK</ApiKey>
   <Data>
     <Recipients>
       <SubscriberLists>
         <SubscriberList>77</SubscriberList>
       </SubscriberLists>
     </Recipients>
     <Content>
       <FromEmail>test@test.com</FromEmail>
       <Subject>Hello!</Subject>
       <Plain>Hello friend, how are you?</Plain>
     </Content>
   </Data>
 </ApiRequest>

 

应答:

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>

全参数设置下发送从外源下载内容的newsletter

请求:
POST https://api.esv2.com/v2/Api/Newsletters 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>2OAEcpz0Rwv3Mhc9nTQK</ApiKey>
   <Data>
     <Recipients>
       <SubscriberLists>
         <SubscriberList>77</SubscriberList>
       </SubscriberLists>
       <SubscriberSegments>
         <SubscriberSegment>1</SubscriberSegment>
         <SubscriberSegment>3</SubscriberSegment>
       </SubscriberSegments>
       <SeedLists>
         <SeedList>1</SeedList>
       </SeedLists>
       <SuppressionLists>
         <SuppressionList>1</SuppressionList>
       </SuppressionLists>
     </Recipients>
     <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>
       <Tags>
         <Tag>tag1</Tag>
         <Tag>tag2</Tag>
       </Tags>
     </Content>
     <DeliverySettings>
       <DeliveryDate>2012-03-23T12:00:00</DeliveryDate>
       <TimeZone>UTC</TimeZone>
       <OverrideDeliveryCap>true</OverrideDeliveryCap>
       <ThrottlingMethod>Manual</ThrottlingMethod>
       <ManualThrottlingTime>10</ManualThrottlingTime>
       <Channels>
         <Channel>
           <Ip>192.168.10.22</Ip>
           <Percentage>70</Percentage>
         </Channel>
         <Channel>
           <Ip>192.168.10.3</Ip>
           <Percentage>30</Percentage>
         </Channel>
       </Channels>
     </DeliverySettings>
   </Data>
 </ApiRequest>

 

发送带有附件的newsletter

POST https://api.esv2.com/v2/Api/Newsletters 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>
     <Recipients>
       <SubscriberLists>
         <SubscriberList>117</SubscriberList>
       </SubscriberLists>
     </Recipients>
     <Content>
       <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的Newsletter

POST https://api.esv2.com/v2/Api/Newsletters 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>
        <Recipients>
            <SubscriberLists>
                <SubscriberList>117</SubscriberList>
            </SubscriberLists>
        </Recipients>
        <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>
    </Data>
</ApiRequest>