Create subscribers list - ExpertSender Help Center

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/attribute	Type	Notes
GeneralSettings	complex	Element containing basic list settings. Required.
AddressSettings	complex	Address settings for list. Optional.
SubscriberSettings	complex	Additional settings concerning subscribers. Optional.
DomainSettings	complex	Domain settings. Optional.
ConfirmationEmail	complex	Confirmation email settings for double opt-in lists. Optional. If not specified, default confirmation email will be used for the list.

GeneralSettings element children:

Element/attribute	Type	Notes
IsSeedList	boolean	Flag indicating if created list will be a regular or seed list. Optional. Default is «false» (regular list).
Name	string	List name. Max 50 characters. Required.
FriendlyName	string	List name visible for subscribers. Max 50 characters. Optional.
Description	string	Internal list description. Optional.
Language	string	List language. Affects default footers, date/number formats etc. Default value is «en-US». Optional. See below for available list languages.
OptInMode	string	Opt-in mode. Default value is «SingleOptIn». Can be specified as «DoubleOptIn» for lists that require sending confirmation email.
Charset	string	Charset (codepage) for emails. Optional. Default is «UTF-8». See below for all supported charsets.
SubscriptionConfirmPageUrl	string	URL subscribers are redirected to after subscribing to the list. Optional. Default is empty (no redirect).
SubscriptionThankYouPageUrl	string	URL subscribers are redirected to after confirming subscription to the list. Optional. Default is empty (no redirect).
RemovalPageUrl	string	URL subscribers are redirected to after unsubscribing from the list. Optional. Default is empty (no redirect).
PreferencesChangeUrl	string	URL 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
zh-Hans
pt-BR
es-ES
it-IT
fr-FR
de-DE
cs-CZ
nl-NL
hu-HU
ro-RO
sk-SK
lt-LT
lv-LV
et-EE
hr-HR
uk-UA
sl-SI
bg-BG
el-GR
sr-Latn
ja-JP

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/attribute	Type	Notes
Company	string	Company name. Optional.
Address	string	Address, first line. Optional.
Address2	string	Address, second line. Optional.
City	string	City. Optional.
ZipPostalCode	string	ZIP or postal code. Optional.

AddressSettings element children:

Element/attribute	Type	Notes
DefaultSubscriberName	string	String used as a default subscriber name if no name is available in the database.
DefaultSubscriberFirstname	string	String used as a default subscriber firstname.
DefaultSubscriberLastname	string	String used as a default subscriber lastname.
FrequencyCappingTimeEmail	integer	Minimal amount of hours between sending two emails to subscribers. Optional. Default is 0 (no limit).
FrequencyCappingTimeSmsMms	integer	Minimal amount of hours between sending two SMS/MMS messages to subscribers. Optional. Default is 0 (no limit).
DisableStandardMessageFooter	boolean	If set to «true» (note the lowercase!), emails to the list will be sent without default message footer. Optional. Default is «false».
DisableListUnsubscribeHeader	boolean	If set to «true» (note the lowercase!), emails to the list will be sent without «List-Unsubscribe:» header. Optional. Default is «false».
AskBeforeUnsubscribing	boolean	If set to «true» (note the lowercase!), subscribers will be asked to confirm unsubscribing from the list (disables «one-click unsubscribe»). Optional. Default is «false».
HideListInPreferenceCenter	boolean	If set to «true» (note the lowercase!), list will not be showed in Preference Center.

DomainSettings element children:

Element/attribute	Type	Notes
ClickTrackingDomain	string	Custom domain that will be used in links in emails sent to the list. Optional. Defaults to standard (unit) settings.

ConfirmationEmail element children:

Element/attribute	Type	Notes
FromName	string	String that will be used in «From:» header of confirmation emails. Required.
FromEmail	string	Email that will be used in «From:» header of confirmation emails. Required.
Subject	string	Confirmation email subject. Required.
Html	string	HTML content of confirmation email. The data should be enclosed in CDATA section for XML transport. See examples. Required.*
Plain	string	Plain 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/attribute	Type	Notes
(Data element content)	int	ID 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>