Import subscribers to list - ExpertSender Help Center

ImportToListTasks collection allows scheduling (asynchronous) imports to subscriber lists. Subscribers are imported from an external source, e.g. file stored on FTP server.

Currently, only one-time, immediately executed imports are supported.

Executing a GET request on ImportToListTasks collection allows polling for scheduled import status (e.g. if it is still in progress or already finished).

Request data format

Data part of request for scheduling a new import to subscribers list.

Data element children:

Element/attribute	Type	Notes
Source	complex	Imported file information. Required.
Target	complex	Target list data. Required.
ImportSetup	complex	Import settings, file settings, column mapping etc. Optional. If omitted, default settings will be used.

Source element children:

Element/attribute	Type	Notes
Url	string	URL address of imported file. Supported protocols are HTTP, HTTPS, FTP, FTPS and SFTP. E.g. ftp://www.domain.com/myimportedfile.csv
Username	string	Username used for authentication. Optional.
Password	string	Password used for authentication. Optional.
FtpAuth	string	Authentication method for secure FTP servers. Optional. Valid values are: None — FTP server does not support secure authentication (default) ExplicitTls — Explicit TLS/SSL authentication ExplicitSsl — Explicit SSL only authentication ImplicitSsl — Implicit SSL authentication
FtpUseActiveMode	boolean	If set to «true», active mode will be used for FTP connections. Default value is «false» — passive connection mode will be used.

Target element children:

Element/attribute	Type	Notes
Name	string	Import name. Used internally for easier identification. Required.
SubscriberList	integer	ID of list that subscribers will be imported to. Required.

ImportSetup element children:

Element/attribute	Type	Notes
Mode	string	Import mode. Import modes are exactly the same as adding modes. Optional. Defaults to «AddAndUpdate».
Delimiter	string	CSV file delimiter. Optional. Default value is ‘,’ (comma).
Quote	string	CSV file quoting character. Optional. Default value is ‘»‘ (double quote).
Escape	string	CSV file escape character. Optional. Default value is ‘»‘ (double quote).
Comment	string	CSV file comment character. Optional. Default value is zero-byte (undefined).
Encoding	string	CSV file encoding. Optional. Default is «utf-8». List of recognized values.
StartingLine	integer	Number of line in file that import will start from. Optional. Default is 0 (from the beginning).
AllowImportingUnsubscribedEmail	boolean	If this flag is set, subscribers that previously unsubscribed from the list on Email channel, will be added again. Default value is «false». Optional.
AllowImportingRemovedByUiEmail	boolean	If this flag is set, subscribers that were removed from Email channel manually using web panel, will be added again. Default value is «true». Optional.
AllowImportingUnsubscribedSmsMms	boolean	If this flag is set, subscribers that previously unsubscribed from the list on SmsMms channel, will be added again. Default value is «false». Optional.
AllowImportingRemovedByUiSmsMms	boolean	If this flag is set, subscribers that were removed from SmsMms channel manually using web panel, will be added again. Default value is «true». Optional.
CheckAllListsForUnsubscribes	boolean	If this flag is set, subscribers who have previously unsubscribed from any list on the Email channel will not be added again. Optional.
Mapping	array[complex]	Array of Column elements, describing column mapping. Optional. If mapping is not specified, system will assume that only first column is to be imported and that it contains email address.
MatchingMode	string	Import key. Possible values: «Email»; «Phone»; «CustomSubscriberId». Optional. Defaults to «Email».

Supported import modes:

Mode	Behaviour
AddAndUpdate	Add new subscribers and update custom fields of subscribers existing on the list.
AddAndReplace	Add new subscribers and replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).
AddAndIgnore	Add new subscribers and do not update or replace custom fields of subscribers existing on the list.
IgnoreAndUpdate	Do not add new subscribers, only update custom fields of subscribers existing on the list.
IgnoreAndReplace	Do not add new subscribers, only replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).
Synchronize	Whole subscribers list will be replaced with imported file content (NOTE: this import mode is available only when sms integration is disabled).

Column element children:

Element/attribute	Type	Notes
Number	integer	Column number from source file. Required. Columns are numbered starting from 0.
Field	string	Name of field or custom property name that column value will be imported into. See below for a list of standard fields. Optional.*
Property	integer	ID of custom property that column value will be imported into. Optional.*

* Importing to a standard field (such as «Email» or «Firstname») requires Field element. If you wish to import to custom property, you may either use Field element and specify custom property name or Property element if you prefer working with custom property IDs. Both ways are supported. Property IDs can be found in ExpertSender web panel.

List of standard fields:

Name	Description
Email	Subscriber’s email.*
EmailMd5	Subscriber’s email md5.**
EmailSha256	Subscriber’s email sha256.**
Phone	Subscriber’s phone number.*
CustomSubscriberId	Subscriber’s custom ID.*
Name	Subscriber name (firstname + lastname).
Firstname	Subscriber first name.
Lastname	Subscriber last name.
Ip	IP address of subscriber.
Vendor	Vendor of subscriber.
TrackingCode	Custom subscriber tracking code.

* Either Email, Phone or CustomSubscriberId must be specified if custom mapping is provided with the request.

** Please note that for importing new subscribers providing Email is required. If you want to update a particular subscriber or import existing subscriber to new list you should provide only one of Email, EmailMd5 or EmailSha256.

Response

Method returns ID of scheduled import. ID can be used to get import status using GET method.

Response Data element:

Element/attribute	Type	Notes
(Data element content)	int	ID of scheduled import.

Examples

Scheduling a new subscribers list import with default options

Request:

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

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>test_api_key1</ApiKey>
   <Data>
     <Source>
       <Url>ftp://ftp.expertsender.com/Lists/test.csv</Url>
     </Source>
     <Target>
       <Name>API test import </Name>
       <SubscriberList>80</SubscriberList>
     </Target>
   </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 12:40:14 GMT 
Content-Length: 147  

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

Scheduling a new subscribers list import with full options

Request:

POST https://api.esv2.com/v2/Api/ImportToListTasks HTTP/1.1 
Accept-Encoding: gzip,deflate 
Content-Type: application/xml;charset=UTF-8 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com 
Content-Length: 1210  

<ApiRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <ApiKey>test_api_key1</ApiKey>
   <Data>
     <Source>
       <Url>ftp://ftp.expertsender.com/Lists/test.csv</Url>
       <Username>username</Username>
       <Password>password</Password>
     </Source>
     <Target>
       <Name>API test import </Name>
       <SubscriberList>80</SubscriberList>
     </Target>
     <ImportSetup>
     <Mode>AddAndUpdate</Mode>
     <Delimiter>,</Delimiter>
     <Quote>"</Quote>
     <Escape>"</Escape>
     <Comment>|</Comment>
     <Encoding>UTF-8</Encoding>
     <StartingLine>1</StartingLine>
     <AllowImportingUnsubscribedEmail>false</AllowImportingUnsubscribedEmail>
     <AllowImportingRemovedByUiEmail>true</AllowImportingRemovedByUiEmail>
     <AllowImportingUnsubscribedSmsMms>false</AllowImportingUnsubscribedSmsMms>
     <AllowImportingRemovedByUiSmsMms>true</AllowImportingRemovedByUiSmsMms>
     <CheckAllListsForUnsubscribes>true</CheckAllListsForUnsubscribes> 
       <Mapping>
         <Column>
           <Number>0</Number>
           <Field>Firstname</Field>
         </Column>
         <Column>
           <Number>1</Number>
           <Field>Lastname</Field>
         </Column>
         <Column>
           <Number>2</Number>
           <Field>Email</Field>
         </Column>
         <Column>
           <Number>3</Number>
           <Property>94</Property>
         </Column>
         <Column>
           <Number>4</Number>
           <Field>age</Field>
         </Column>
         <Column>
           <Number>5</Number>
           <Field>Phone</Field>
         </Column>
         <Column>
           <Number>6</Number>
           <Field>CustomSubscriberId</Field>
         </Column>
       </Mapping>
     </ImportSetup>
   </Data>
</ApiRequest>