Skip to content

Create subscribers list

Lists collection allows creating new subscriber lists. Created lists can then be used to import subscribers or add them manually using API, panel or any other available method.

Request data format

Data part of request for creating a new subscribers list.

Data element children:

Element/attributeTypeNotes
GeneralSettingscomplexElement containing basic list settings. Required.
AddressSettingscomplexAddress settings for list. Optional.
SubscriberSettingscomplexAdditional settings concerning subscribers. Optional.
DomainSettingscomplexDomain settings. Optional.
ConfirmationEmailcomplexConfirmation email settings for double opt-in lists. Optional. If not specified, default confirmation email will be used for the list.

GeneralSettings element children:

Element/attributeTypeNotes
IsSeedListbooleanFlag indicating if created list will be a regular or seed list. Optional. Default is “false” (regular list).
NamestringList name. Max 50 characters. Required.
FriendlyNamestringList name visible for subscribers. Max 50 characters. Optional.
DescriptionstringInternal list description. Optional.
LanguagestringList language. Affects default footers, date/number formats etc. Default value is “en-US”. Optional. See below for available list languages.
OptInModestringOpt-in mode. Default value is “SingleOptIn”. Can be specified as “DoubleOptIn” for lists that require sending confirmation email.
CharsetstringCharset (codepage) for emails. Optional. Default is “UTF-8”. See below for all supported charsets.
SubscriptionConfirmPageUrlstringURL subscribers are redirected to after subscribing to the list. Optional. Default is empty (no redirect).
SubscriptionThankYouPageUrlstringURL subscribers are redirected to after confirming subscription to the list. Optional. Default is empty (no redirect).
RemovalPageUrlstringURL subscribers are redirected to after unsubscribing from the list. Optional. Default is empty (no redirect).
PreferencesChangeUrlstringURL subscribers are redirected to after changing their preferences on “Preference Center” page. Optional. Default is empty (no redirect). 
Supported list languages
en-US
pl-PL
ru-RU
Supported list charsets
UTF-8
ISO-8859-1
ISO-8859-2

Note: Language and charset list is a subject to change. Ask ExpertSender Support if your preferred language/charset could be supported.

AddressSettings element children:

Element/attributeTypeNotes
CompanystringCompany name. Optional.
AddressstringAddress, first line. Optional.
Address2stringAddress, second line. Optional.
CitystringCity. Optional.
ZipPostalCodestringZIP or postal code. Optional.

AddressSettings element children:

Element/attributeTypeNotes
DefaultSubscriberNamestringString used as a default subscriber name if no name is available in the database.
DefaultSubscriberFirstnamestringString used as a default subscriber firstname.
DefaultSubscriberLastnamestringString used as a default subscriber lastname.
FrequencyCappingTimeEmailintegerMinimal amount of hours between sending two emails to subscribers. Optional. Default is 0 (no limit).
FrequencyCappingTimeSmsMmsintegerMinimal amount of hours between sending two SMS/MMS messages to subscribers. Optional. Default is 0 (no limit).
DisableStandardMessageFooterbooleanIf set to “true” (note the lowercase!), emails to the list will be sent without default message footer. Optional. Default is “false”.
DisableListUnsubscribeHeaderbooleanIf set to “true” (note the lowercase!), emails to the list will be sent without “List-Unsubscribe:” header. Optional. Default is “false”.
AskBeforeUnsubscribingbooleanIf set to “true” (note the lowercase!), subscribers will be asked to confirm unsubscribing from the list (disables “one-click unsubscribe”). Optional. Default is “false”.
HideListInPreferenceCenterbooleanIf set to “true” (note the lowercase!), list will not be showed in Preference Center.

DomainSettings element children:

Element/attributeTypeNotes
ClickTrackingDomainstringCustom domain that will be used in links in emails sent to the list. Optional. Defaults to standard (unit) settings.

ConfirmationEmail element children:

Element/attributeTypeNotes
FromNamestringString that will be used in “From:” header of confirmation emails. Required.
FromEmailstringEmail that will be used in “From:” header of confirmation emails. Required.
SubjectstringConfirmation email subject. Required.
HtmlstringHTML content of confirmation email. The data should be enclosed in CDATA section for XML transport. See examples. Required.*
PlainstringPlain text content of confirmation email. Required.*

*For maximum accessibility, confirmation emails are required to have both HTML and plain text contents. This is a special case. There is no such requirement for regular emails such as newsletters.

Response

Method returns ID of created subscriber list. ID can be used e.g. to schedule import to this list.

Response Data element:

Element/attributeTypeNotes
(Data element content)intID of created list.

Examples

Creating new subscribers list with default options

Request:

POST https://api.esv2.com/v2/Api/Lists HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: application/xml 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 278 

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <ApiKey>test_api_key1</ApiKey>
  <Data>
    <GeneralSettings>
      <Name>API test list</Name>
    </GeneralSettings>
  </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: Thu, 05 Apr 2012 15:25:57 GMT 
Content-Length: 147 

<ApiResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Data>33</Data>
</ApiResponse>

Creating new subscribers list with full options

Request:

POST https://api.esv2.com/v2/Api/Lists HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: application/xml 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 1983 

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>test_api_key1</ApiKey>
   <Data>
     <GeneralSettings>
       <Name>API test list</Name>
       <FriendlyName>Best offers!</FriendlyName>
       <Description>This is a test list created using API</Description>
       <Language>en-US</Language>
       <OptInMode>DoubleOptIn</OptInMode>
       <Charset>ISO-8859-1</Charset>
       <SubscriptionConfirmPageUrl>
         http://www.test.com
       </SubscriptionConfirmPageUrl>
       <SubscriptionThankYouPageUrl>
         http://www.test.com
       </SubscriptionThankYouPageUrl>
       <RemovalPageUrl>http://www.test.com</RemovalPageUrl>
       <PreferencesChangeUrl>http://www.test.com</PreferencesChangeUrl>
     </GeneralSettings>
     <AddressSettings>
       <Company>TestCompany</Company>
       <Address>Test Blvd.</Address>
       <Address2>123</Address2>
       <City>New York</City>
       <ZipPostalCode>12345</ZipPostalCode>
       <StateProvinceRegion>CA</StateProvinceRegion>
       <Country>USA</Country>
     </AddressSettings>
     <SubscriberSettings>
       <DefaultSubscriberName>Respectful Customer</DefaultSubscriberName>
       <DefaultSubscriberFirstname>Customer</DefaultSubscriberFirstname>
       <DefaultSubscriberLastname>Respectful</DefaultSubscriberLastname>
       <FrequencyCappingTimeEmail>12</FrequencyCappingTimeEmail>
       <FrequencyCappingTimeSmsMms>24</FrequencyCappingTimeSmsMms>
       <DisableStandardMessageFooter>true</DisableStandardMessageFooter>
       <DisableListUnsubscribeHeader>true</DisableListUnsubscribeHeader>
       <AskBeforeUnsubscribing>true</AskBeforeUnsubscribing>
     </SubscriberSettings>
     <DomainSettings>
       <ClickTrackingDomain>testdomain.com</ClickTrackingDomain>
     </DomainSettings>
     <ConfirmationEmail>
       <FromName>Test</FromName>
       <FromEmail>test@test.pl</FromEmail>
       <Subject>to jest testowy subject</Subject>
       <Html>
         <![CDATA[<a href="*[link_confirm]*">Confirm subscription</a>]]>
       </Html>
       <Plain>Confirm your subscription: *[link_confirm]*</Plain>
     </ConfirmationEmail>
   </Data>
</ApiRequest>
On this page
To top