Create and send newsletter - ExpertSender Help Center

Newsletters collection allows creating and sending Web Push newsletter messages.

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.*
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.

*Web Push Newsletter has to have at least one subscriber list or subscriber segment.

Content element children:

Element/attribute	Type	Notes
Subject	string	Web Push Newsletter subject. Required.
Body	string	Web Push Newsletter body. Required.
Link	string	Web Push Newsletter link. Required.
BigImageFromBase64	complex	Web Push Newsletter big image. Works only on Chrome. Optional.
BigImageFromUrl	string	Web Push Newsletter big image. Works only on Chrome. You can enter the address of the image that will be downloaded. Acceptable JPEG, PNG extensions. Max size of image is 200KB. Optional.
IconFromBase64	complex	Web Push Newsletter icon. Optional but required for open tracking.
IconFromUrl	string	Web Push Newsletter icon. Optional but required for open tracking. You can enter the address of the image that will be downloaded. Acceptable JPEG, PNG extensions. Max size of image is 200KB.
Action1	complex	Web Push Newsletter Action 1 button. Optional.
Action2	complex	Web Push Newsletter Action 2 button. 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. Optional.
UrlIntegrations	complex	List of IDs of URL integrations that were created in Business unit settings. Optional.
RequireInteraction	boolean	The User must click or dismiss the notification. By default set to “true”. 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.

Action1 and Action2 element children:

Element/attribute	Type	Notes
Title	string	Web Push Action button title. Required.
Url	string	Web Push Action button Url. Required.
IconFromBase64	complex	Web Push Newsletter icon. Optional but required for open tracking.
IconFromUrl	string	Web Push Action button icon. Optional. You can enter the address of the image that will be downloaded. Acceptable JPEG, PNG extensions. Max size of image is 200KB

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 “WebPush”.

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>

BigImageFromBase64 and IconFromBase64 elements children:

Element/attribute	Type	Notes
FileName	string	Image file name. Required.
Content	string	Image content encoded with the Base64*. Required.

*Note: Binary to Base64 encoding is available in most programing 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.

Delivery throttling methods:

Name	Behaviour
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.
Manual	Manual throttling. Delivery time is specified manually as a number of hours the whole delivery will take.

Response

Method returns ID of created newsletter.

Response Data element:

Element/attribute	Type	Notes
(Data element content)	int	ID of created newsletter.

Examples

Sending a simple newsletter

Request:

POST https://api.esv2.com/v2/Api/WebPushNewsletters 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>test_api_key</ApiKey>
  <Data>
    <Recipients>
      <SubscriberSegments>
        <SubscriberSegment>1074</SubscriberSegment>
      </SubscriberSegments>
      <ExcludedLists>
         <SubscriberList>7484</SubscriberList>
       </ExcludedLists>
       <ExcludedSegments>
         <SubscriberSegment>3400</SubscriberSegment>
       </ExcludedSegments>
    </Recipients>
    <Content>
      <Subject>Hello!</Subject>
      <Body>Hello friend, how are you?</Body>
      <Link>https://www.google.com</Link>
    </Content>
  </Data>
</ApiRequest>

Response:

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>

Sending a simple newsletter with action buttons, tags, Google Analytics Tags and images

POST https://api.esv2.com/v2/Api/WebPushNewsletters 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>test_api_key</ApiKey>
  <Data>
    <Recipients>
      <SubscriberSegments>
        <SubscriberSegment>1074</SubscriberSegment>
      </SubscriberSegments>
    </Recipients>
    <Content>
      <Subject>Hello!</Subject>
      <Body>Hello friend, how are you?</Body>
      <Link>https://www.google.com</Link>
<BigImageFromUrl>https://www.google.pl/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png</BigImageFromUrl>
      <IconFromBase64>
        <FileName>test.jpg</FileName><Content>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
...
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G</Content>
      </IconFromBase64>
      <Tags>
        <Tag>actions</Tag>
        <Tag>buttons</Tag>
      </Tags>
      <GoogleAnalyticsTags>
        <Campaign>testcampaign</Campaign>
        <Source>testsource</Source>
        <Content>testcontent</Content>
      </GoogleAnalyticsTags>
      <Action1>
        <Title>ExpertSender</Title>
        <Url>https://expertsender.com/</Url>
        <IconFromBase64>
          <FileName>test.jpg</FileName>
    <Content>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFIvTGFu
ZyhwbC1QTCkgL1N0cnVjdFRyZWVSb290IDggMCBSL01hcmtJbmZvPDwvTWFya2VkIHRydWU+Pj4+
DQplbmRvYmoNCjIgMCBvYmoNCjw8L1R5cGUvUGFnZXMvQ291bnQgMS9LaWRzWyAzIDAgUl0gPj4N
CmVuZG9iag0KMyAwIG9iag0KPDwvVHlwZS9QYWdlL1BhcmVudCAyIDAgUi9SZXNvdXJjZXM8PC9G
...
ODlFOENBQTNGMTY5NzFBRTU+XSAvUHJldiA4MjU0MS9YUmVmU3RtIDgyMjcwPj4NCnN0YXJ0eHJl
Zg0KODMwNTcNCiUlRU9G</Content>
        </IconFromBase64>
      </Action1>
      <Action2>
        <Title>Request a demo</Title>
        <Url>https://expertsender.com/company/free-demo-request/</Url>
      </Action2>
    </Content>
  </Data>
</ApiRequest>