Skip to content

Create and send newsletter

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/attributeTypeNotes
RecipientscomplexNewsletter recipients’ information. Required.
ContentcomplexContent information. Required.
DeliverySettingscomplexDelivery settings (delivery date, throttling, etc). Optional. If omitted, default delivery settings will be used.

Recipients element children:

Element/attributeTypeNotes
SubscriberListsarray[integer]Array of SubscriberList elements containing IDs of subscriber lists that newsletter will be sent to. Optional.*
SubscriberSegmentsarray[integer]Array of SubscriberSegment elements containing IDs of subscriber segments that newsletter will be sent to. Optional.*
ExcludedListsarray[integer]An array of SubscriberList elements containing the IDs of the subscriber lists to which the newsletter will be excluded from mailing. Optional.
ExcludedSegmentsarray[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/attributeTypeNotes
SubjectstringWeb Push Newsletter subject. Required.
BodystringWeb Push Newsletter body. Required.
Linkstring Web Push Newsletter link. Required.
BigImageFromBase64complexWeb Push Newsletter big image. Works only on Chrome. Optional.
BigImageFromUrlstringWeb 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.
IconFromBase64complexWeb Push Newsletter icon. Optional but required for open tracking.
IconFromUrlstringWeb 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.
Action1complex Web Push Newsletter Action 1 button. Optional.
Action2complexWeb Push Newsletter Action 2 button. Optional.
GoogleAnalyticsTagscomplexGoogle Analytics tags used to decorate links inside newsletter’s content. Optional. If omitted, Google Analytics will be disabled for created newsletter. Optional.
UrlIntegrationscomplexList of IDs of URL integrations that were created in Business unit settings. Optional.
RequireInteractionbooleanThe User must click or dismiss the notification. By default set to “true”. Optional.
EnableClickTrackbooleanIf set to “false”, clicks won’t be tracked. By default set to “true”. Optional.
EnableOpenTrackbooleanIf set to “false”, opens won’t be tracked. By default set to “true”. Optional.

Action1 and Action2 element children:

Element/attributeTypeNotes
TitlestringWeb Push Action button title. Required.
Urlstring Web Push Action button Url. Required.
IconFromBase64complexWeb Push Newsletter icon. Optional but required for open tracking.
IconFromUrlstringWeb 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/attributeTypeNotes
CampaignstringGoogle Analytics tag “utm_campaign”. Optional.
SourcestringGoogle Analytics tag “utm_source”. Optional.
ContentstringGoogle Analytics tag “utm_content”. Optional.

Note: The remaining tag, “utm_medium” is by default specified as “WebPush”.

UrlIntegrations element children:

Element/attributeTypeNotes
IdintId 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/attributeTypeNotes
FileNamestringImage file name. Required.
ContentstringImage 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/attributeTypeNotes
DeliveryDatedateTimeNewsletter delivery date. Optional. By default, newsletter will be sent immediately.
TimeZonestringTime zone used with specified delivery date. Optional. Defaults to standard (unit) settings. List of valid values.
OverrideDeliveryCapbooleanIf set to “true”, newsletter will ignore any delivery frequency capping settings. Optional. Default is “false”.
ThrottlingMethodstringDelivery throttling method. See below for description of different throttling methods. Optional. Default is “None”.
ManualThrottlingTimeintTime (in hours) of manual delivery throttling. This setting is required if ThrottlingMethod was set to “Manual” and ignored in other cases.

Delivery throttling methods:

NameBehaviour
NoneDelivery will not be throttled. Newsletter will be sent as quickly as possible. This is a default method, but not recommended for delivering large volumes.
ManualManual 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/attributeTypeNotes
(Data element content)intID 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>
On this page
To top