Create and send newsletter - ExpertSender Help Center

SmsMmsNewsletters collection allows creating and sending SMS/MMS 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.*
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 od 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
Sender	string	Name of SMS/MMS gateway that was created in Business unit settings. Required.
CampaignDescription	string	Campaign description. Required.
Plain	string	Plain text content of newsletter. Required.
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.
EnableClickTrack	boolean	If set to “false”, clicks won’t be tracked. By default set to “true”. Optional.

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

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

* Note: The minimum throttling is 60 messages per minute. Longer throttling will be automatically adjusted.

Response

Method returns ID of created newsletter. ID can be used to pause or resume newsletters with status “InProgress” (see Pause or resume newsletter (SMS)).

Response Data element:

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

Example

Sending a simple newsletter

Request:

POST https://api.esv2.com/v2/Api/SmsMmsNewsletters 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: 471  

<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>
       <Sender>SmsGateway</Sender>
       <CampaignDescription>Hello!</CampaignDescription>
       <Plain>Hello friend, how are you?</Plain>
     </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 newsletter with full options

Request:

POST https://api.esv2.com/v2/Api/SmsMmsNewsletters 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>
       <Sender>SmsGateway</Sender>
       <CampaignDescription>Hello!</CampaignDescription>
       <Plain>Hello friend, how are you?</Plain>
       <GoogleAnalyticsTags>
         <Campaign>testcampaign</Campaign>
         <Source>testsource</Source>
         <Content>testcontent</Content>
       </GoogleAnalyticsTags>
       <Tags>
         <Tag>tag1</Tag>
         <Tag>tag2</Tag>
       </Tags>
       <EnableClickTrack>false</EnableClickTrack>
     </Content>
     <DeliverySettings>
       <DeliveryDate>2018-03-23T12:00:00</DeliveryDate>
       <TimeZone>UTC</TimeZone>
       <OverrideDeliveryCap>true</OverrideDeliveryCap>
       <ThrottlingMethod>Manual</ThrottlingMethod>
       <ManualThrottlingTime>10</ManualThrottlingTime>
     </DeliverySettings>
   </Data>
</ApiRequest>