Przejdź do treści

Create and send newsletter

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/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.*
SeedListsarray[integer]Array of SeedList elements containing IDs of seed lists used during shipment. Optional.*
SuppressionListsarray[integer]Array of SuppressionList elements containing IDs od suppression lists that will be checked during shipment. 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.

* 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/attributeTypeNotes
SenderstringName of SMS/MMS gateway that was created in Business unit settings. Required.
CampaignDescriptionstringCampaign description. Required.
PlainstringPlain text content of newsletter. Required.
GoogleAnalyticsTagscomplexGoogle Analytics tags used to decorate links inside newsletter’s content. Optional. If omitted, Google Analytics will be disabled for created newsletter.
Tagsarray[string]List of tags used to mark the newsletter for convenience reasons. Optional.
EnableClickTrackbooleanIf set to “false”, clicks won’t be tracked. By default set to “true”. Optional.

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

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:

NameBehavior
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.
AutoAutomatic 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/attributeTypeNotes
(Data element content)intID 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>
Na tej stronie
Do góry