Skip to content

Import subscribers to list

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/attributeTypeNotes
SourcecomplexImported file information. Required.
TargetcomplexTarget list data. Required.
ImportSetupcomplexImport settings, file settings, column mapping etc. Optional. If omitted, default settings will be used.

Source element children:

Element/attributeTypeNotes
UrlstringURL address of imported file. Supported protocols are HTTP, HTTPS, FTP, FTPS and SFTP. E.g. ftp://www.domain.com/myimportedfile.csv
UsernamestringUsername used for authentication. Optional.
PasswordstringPassword used for authentication. Optional.
FtpAuthstringAuthentication method for secure FTP servers. Optional. Valid values are:None – FTP server does not support secure authentication (default)ExplicitTls – Explicit TLS/SSL authenticationExplicitSsl – Explicit SSL only authenticationImplicitSsl – Implicit SSL authentication
FtpUseActiveModebooleanIf 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/attributeTypeNotes
NamestringImport name. Used internally for easier identification. Required.
SubscriberListintegerID of list that subscribers will be imported to. Required.

ImportSetup element children:

Element/attributeTypeNotes
ModestringImport mode. Import modes are exactly the same as adding modes. Optional. Defaults to “AddAndUpdate”.
DelimiterstringCSV file delimiter. Optional. Default value is ‘,’ (comma).
QuotestringCSV file quoting character. Optional. Default value is ‘”‘ (double quote).
EscapestringCSV file escape character. Optional. Default value is ‘”‘ (double quote).
CommentstringCSV file comment character. Optional. Default value is zero-byte (undefined).
EncodingstringCSV file encoding. Optional. Default is “utf-8”. List of recognized values.
StartingLineintegerNumber of line in file that import will start from. Optional. Default is 0 (from the beginning).
AllowImportingUnsubscribedEmailbooleanIf this flag is set, subscribers that previously unsubscribed from the list on Email channel, will be added again. Default value is “false”. Optional.
AllowImportingRemovedByUiEmailbooleanIf this flag is set, subscribers that were removed from Email channel manually using web panel, will be added again. Default value is “true”. Optional.
AllowImportingUnsubscribedSmsMmsbooleanIf this flag is set, subscribers that previously unsubscribed from the list on SmsMms channel, will be added again. Default value is “false”. Optional.
AllowImportingRemovedByUiSmsMmsbooleanIf this flag is set, subscribers that were removed from SmsMms channel manually using web panel, will be added again. Default value is “true”. Optional.
CheckAllListsForUnsubscribesbooleanIf this flag is set, subscribers who have previously unsubscribed from any list on the Email channel will not be added again. Optional.
Mappingarray[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.
MatchingModestringImport key. Possible values: “Email”; “Phone”; “CustomSubscriberId”. Optional. Defaults to “Email”.

Supported import modes:

ModeBehaviour
AddAndUpdateAdd new subscribers and update custom fields of subscribers existing on the list.
AddAndReplaceAdd new subscribers and replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).
AddAndIgnoreAdd new subscribers and do not update or replace custom fields of subscribers existing on the list.
IgnoreAndUpdateDo not add new subscribers, only update custom fields of subscribers existing on the list.
IgnoreAndReplaceDo not add new subscribers, only replace custom fields of subscribers existing on the list (NOTE: all previous values of custom fields will be erased).
SynchronizeWhole 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/attributeTypeNotes
NumberintegerColumn number from source file. Required. Columns are numbered starting from 0.
FieldstringName of field or custom property name that column value will be imported into. See below for a list of standard fields. Optional.*
PropertyintegerID 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:

NameDescription
EmailSubscriber’s email.*
EmailMd5Subscriber’s email md5.**
EmailSha256Subscriber’s email sha256.**
PhoneSubscriber’s phone number.* 
CustomSubscriberIdSubscriber’s custom ID.*
NameSubscriber name (firstname + lastname).
FirstnameSubscriber first name.
LastnameSubscriber last name.
IpIP address of subscriber.
VendorVendor of subscriber.
TrackingCodeCustom 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/attributeTypeNotes
(Data element content)intID 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>
On this page
To top