Create and send newsletter
Newsletters collection allows creating and sending newsletter messages. Content can either be sent along with the request or stored on an external source (e.g. FTP server).
For this method, all request data should be provided in XML or JSON format. Responses, depending on the format provided, are also generated as XML or JSON data.
The content type for such a request should be set to text/xml or application/json.
Request data format
Data part of request for creating a new newsletter.
Data element children:
Element/attribute | Type | Notes |
---|---|---|
Recipients | complex | Newsletter recipients’ information. Required. |
Content | complex | Content information. Required. |
DeliverySettings | complex | Delivery settings (delivery date, throttling, etc). Optional. If omitted, default delivery settings will be used. |
Recipients element children:
Element/attribute | Type | Notes |
---|---|---|
SubscriberLists | array[integer] | Array of SubscriberList elements containing IDs of subscriber lists that newsletter will be sent to. Optional.* |
SubscriberSegments | array[integer] | Array of SubscriberSegment elements containing IDs of subscriber segments that newsletter will be sent to. Optional.* |
SeedLists | array[integer] | Array of SeedList elements containing IDs of seed lists used during shipment. Optional.* |
SuppressionLists | array[integer] | Array of SuppressionList elements containing IDs of suppression lists that will be checked during shipment. Optional. |
ExcludedLists | array[integer] | An array of SubscriberList elements containing the IDs of the subscriber lists to which the newsletter will be excluded from mailing. Optional. |
ExcludedSegments | array[integer] | An array of SubscriberSegment elements containing the IDs of the subscriber segments to which the newsletter will be excluded from mailing. Optional. |
* Newsletter has to have at least one subscriber list, subscriber segment or seed list specified. Empty recipients element will trigger appropriate error message.
Content element children:
Element/attribute | Type | Notes |
---|---|---|
FromName | string | String put into “From:” header. Required. |
FromEmail | string | Email put into “From:” header. Required. |
ReplyToName | string | String put into “Reply-To:” header. Optional. |
ReplyToEmail | string | Email put into “Reply-To:” header. Optional. |
Subject | string | Newsletter subject. Required. |
Html | string | HTML content of newsletter. The data should be enclosed in CDATA section for XML transport. See examples. Optional.* |
Plain | string | Plain text content of newsletter. Optional.* |
AmpHtml | string | AMP HTML content of newsletter. The data should be enclosed in CDATA section for XML transport. See examples. Optional.* |
Preheader | string | Newsletter preheader. Optional. |
Header | integer | ID of header template to use. Optional. |
Footer | integer | ID of footer template to use. Optional. |
ContentFromUrl | complex | Used if content is not inside XML request but has to be downloaded from external source. Optional.* |
GoogleAnalyticsTags | complex | Google Analytics tags used to decorate links inside newsletter’s content. Optional. If omitted, Google Analytics will be disabled for created newsletter. |
Tags | array[string] | List of tags used to mark the newsletter for convenience reasons. Optional. |
Attachments | complex | Collection of „Attachment” elements, containing additional attachment data (e.g. encoded PDF files sent with the newsletter). Optional.** |
UrlIntegrations | complex | List of IDs of URL integrations that were created in Business unit settings. Optional. |
EnableClickTrack | boolean | If set to “false”, clicks won’t be tracked. By default set to “true”. Optional. |
EnableOpenTrack | boolean | If set to “false”, opens won’t be tracked. By default set to “true”. Optional. |
* You may either put content of newsletter inside using Html, Plain and/or AmpHtml elements or specify that content is to be downloaded from external source (such as webpage or FTP server as zipped file with HTML and images) using ContentFromUrl element. If content was not found in either place, an error message will be returned. If there are more than one Html, Plain and/or AmpHtml files only the last file will be the content of message. If you would like to send AMP Html you should provide Html and/or Plain as a fallback version of email.
AMP Html content must contain all needed elements (see examples) and all links must be secure links (like https://)
** It is not possible to have both ContentFromUrl and Attachments elements at the same time.
Note: If you wish to send inline images within your newsletter, using ContentFromUrl method is the only way to do it.
ContentFromUrl element children:
Element/attribute | Type | Notes |
---|---|---|
Url | string | URL address of imported file. Supported protocols are HTTP, HTTPS, FTP, FTPS and SFTP. E.g. ftp://www.domain.com/mycreative.zip |
Username | string | Username used for authentication. Optional. |
Password | string | Password used for authentication. Optional. |
FtpAuth | string | Authentication method for secure FTP servers. Optional. Valid values are: None – FTP server does not support secure authentication (default) ExplicitTls – Explicit TLS/SSL authentication ExplicitSsl – Explicit SSL only authentication ImplicitSsl – Implicit SSL authentication |
FtpUseActiveMode | boolean | If set to „true”, active mode will be used for FTP connections. Default value is „false” – passive connection mode will be used. |
GoogleAnalyticsTags element children:
Element/attribute | Type | Notes |
---|---|---|
Campaign | string | Google Analytics tag „utm_campaign”. Optional. |
Source | string | Google Analytics tag „utm_source”. Optional. |
Content | string | Google Analytics tag „utm_content”. Optional. |
Note: The remaining tag, „utm_medium” is by default specified as „Email”.
Attachment element children:
Element/attribute | Type | Notes |
---|---|---|
FileName | string | Attachment filename. E.g. „infosheet.pdf”. Should be unique (no 2 attachments should have the same filename). Required. |
MimeType | string | File type according to MIME standards. E.g. „application/pdf”. If omitted, default MIME type will be used: „application/octet-stream”. Optional. MIME type can affect how email attachments are treated in different email clients, so it is advisable to always specify the correct type.* |
Content | string | Attachment file content. Must be Base64 encoded.** See example requests. Required. |
* Note: For list of MIME types for different files, see: http://en.wikipedia.org/wiki/Internet_media_type
** Note: Binary to Base64 encoding is available in most programming languages. For more information about Base64 encoding, see: http://en.wikipedia.org/wiki/Base64
DeliverySettings element children:
Element/attribute | Type | Notes |
---|---|---|
DeliveryDate | dateTime | Newsletter delivery date. Optional. By default, newsletter will be sent immediately. |
TimeZone | string | Time zone used with specified delivery date. Optional. Defaults to standard (unit) settings. List of valid values. |
OverrideDeliveryCap | boolean | If set to „true”, newsletter will ignore any delivery frequency capping settings. Optional. Default is „false”. |
ThrottlingMethod | string | Delivery throttling method. See below for description of different throttling methods. Optional. Default is „None”. |
ManualThrottlingTime | int | Time (in hours) of manual delivery throttling. This setting is required if ThrottlingMethod was set to „Manual” and ignored in other cases. |
TimeOptimizationPeriod | string | Time of delivery for Sending Time Optimization (STO). This setting is only used if ThrottlingMethod was set to „TimeOptimized” and is ignored in other cases. Valid values are: „24h” (24 hours – default) and „7d” (7 days). |
Channels | array[complex] | Array of Channel elements describing delivery channels. Optional. If omitted, standard (unit) channel settings will be used to deliver the newsletter. |
Delivery throttling methods:
Name | Behavior |
---|---|
None | Delivery will not be throttled. Newsletter will be sent as quickly as possible. This is a default method, but not recommended for delivering large volumes. |
Auto | Automatic throttling. Delivery time will be automatically calculated, depending on number of recipients and unit settings. |
Manual | Manual throttling. Delivery time is specified manually as a number of hours the whole delivery will take. |
TimeOptimized | Sending Time Optimization (STO). Date of delivery will be calculated for each subscriber based on their previous performance over the next 24h/7d. |
TimeTravel | Time Travel. Date of delivery will be calculated for each subscriber based on their timezone. |
Channel element children:
Element/attribute | Type | Notes |
---|---|---|
Ip | string | Delivery channel IP address. |
Percentage | integer | Portion (%) of emails that will be sent using this delivery channel.* |
* The sum of percentage for all selected channels must be 100% or an error message will occur. Example configuration could be 2 channels with 30/70 ratio or 3 channels with 25/25/50 ratio. A list of available channels can be found in unit settings, in ExpertSender panel.
UrlIntegrations element children:
Element/attribute | Type | Notes |
---|---|---|
ID | int | Id number of existing, not deleted integration. Required. |
Example:
<UrlIntegrations>
<UrlIntegration>
<Id>30</Id>
</UrlIntegration>
<UrlIntegration>
<Id>32</Id>
</UrlIntegration>
</UrlIntegrations>
Response
Method returns ID of created newsletter. ID can be used to retrieve message statistics (see /Api/MessageStatistics) to ascertain newsletters progress.
Response Data element:
Element/attribute | Type | Notes |
---|---|---|
(Data element content) | int | ID of created newsletter. |
Examples
Sending a simple newsletter
Request in XML format:
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>
<ExcludedLists>
<SubscriberList>7484</SubscriberList>
</ExcludedLists>
<ExcludedSegments>
<SubscriberSegment>3400</SubscriberSegment>
</ExcludedSegments>
</Recipients>
<Content>
<FromEmail>test@test.com</FromEmail>
<Subject>Hello!</Subject>
<Plain>Hello friend, how are you?</Plain>
</Content>
</Data>
</ApiRequest>
Response in XML format:
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>
Request in JSON format:
POST https://api.esv2.com/v2/Api/Newsletters HTTP/1.1
Content-Type: application/json
User-Agent: Mozilla/5.0
Host: api.esv2.com
Accept-Encoding: gzip, deflate, br
Content-Length: 395
{
"ApiKey": "YOUR_API_KEY",
"Data": {
"Recipients": {
"SubscriberSegments": [
2816,2815
]
},
"Content": {
"FromEmail": "test@test.com",
"Subject": "Hello!",
"ContentFromUrl": {
"Url": "http://test.expertsender/test_1.zip"},
"Tags": [
"tag1",
"tag2"
]
}
}
}
Response in JSON format:
HTTP/1.1 201 Created
Cache-Control: private
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
Date: Fri, 26 Apr 2024 08:09:10 GMT
Content-Length: 21
{
"Data": 33322
}
Sending newsletter with content downloaded from external source and full options
Request:
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>
Sending newsletter with attachment
Request:
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>
Note: Part of long attachment content was cut and „…” was inserted.
Sending newsletter with AMP Html content
Request:
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>