This method creates and automatically starts an import process for the contacts listed in the xmlDoc parameter. You can use this method instead of calling a sequence of NewImportProcess and StartProcess methods. StartImportProcesses can also be used to update fields of an existing contact.
This method creates and automatically starts an import process for the contacts listed in the xmlDoc parameter. You can use this method instead of calling a sequence of NewImportProcess and StartProcess methods. StartImportProcesses can also be used to update fields of an existing contact. Please note that, while updating, empty parameters are handled as "do not update this field", not as "overwrite with an empty value".
Method
...
public string StartImportProcesses(string listsIDs, string listsGUIDs, string xmlDoc, string groupsIDs, int importType, int mobileInputType, bool asPending, bool ConfirmEmail, bool asOptOut, bool forceOptIn, bool replaceGroups)
Method parameters
...
parameters
Mandatory fields must be specified even when they are empty. Optional fields (can be skipped if you want to use the default value) are written in in blue.
Parameter | |
---|---|
listsIDs |
...
- 1= include international code
- 2=international code and phone number in two different fields
...
Lists and groups
At least one between listsIDs and listsGUIDs must contain a value. If you specify both fields IDs and GUIDs must match. You may specify more than one list, separated by semicolon (e.g. listsIDs = "84;85;86" to import contacts to lists 84, 85, 86). See example below.
...
language | html/xml |
---|---|
title | Lists and groups (example) |
collapse | true |
...
| List identifiers. You can include multiple list IDs, separated by semicolons. Example: |
listsGUIDs string | List GUIDs. You can include multiple list GUIDs, separated by semicolons. Example: |
groupsIDs string | Group identifiers for each list, separated by semicolons. You can specify multiple groups for each list as well, separated by commas. Example: |
xmlDoc | An XML string containing the recipients to be imported to the specified lists and groups. (See "XML Structure" section below for more information and examples.) |
importType integer | Import type. (Default = 3) |
mobileInputType integer | Mobile number input type.
(See "XML Structure" section below for more information and examples.) |
asPending boolean | optional - Import recipients as "pending" when set to true. (Default = false) |
ConfirmEmail boolean | optional - Sends a confirmation request email when set to true. The system will automatically create the confirmation email based on a default template. (Default = false) |
asOptOut boolean | optional - Imports recipients as "unsubscribed" when set to true. (Default = false) |
forceOptIn boolean | optional - Imports recipients as "subscribed" when set to true. This will re-subscribe recipients that have previously unsubscribed. (Default = false) |
replaceGroups boolean | optional - Replace existing groups when set to true. The system will automatically remove previously subscribed groups and keep only the groups specified in the groupsIDs parameter.(Default = false) |
Note |
---|
An HTTP 500 Error is returned if optional parameters are included in the request with an empty value (Ex: |
Lists and Groups
You must specify at least one of the listIDs
or listsGUIDs
parameters. If you specify both fields, then the number of items in each parameter must match, and you must use semicolons to delineate empty values. We've provided examples below to help with understanding how to work with these parameters.
Add recipients to a single list (no groups)
In this example, we specify both the listsIDs
and the listsGUIDs
parameters. There are no groups, so we include an empty groupsIDs
tag.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<ws:listsIDs>1</ws:listsIDs> <ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs> <ws:groupsIDs>22<groupsIDs></ws:groupsIDs> <!--Add to list 1 (groups 22 and 23, only list GUID is specified)--> |
Add recipients to a single list (single group)
In this example, we specify both the listsIDs
and the listsGUIDs
parameters, and since there is a single group we include it in the groupsIDs
parameter.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<ws:listsIDs>1</ws:listsIDs> <ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs> <!--Use comma to separate groups that belong to the same list--> <ws:groupsIDs>22,23<<ws:groupsIDs>22</ws:groupsIDs> <!--Add to list 1 (group 22) and to list 2 (group 13)--> <ws:listsIDs>1;2</ws:listsIDs> |
Add recipients to a single list (multiple groups)
In this example, we specify only the listsGUIDs
parameter. There are multiple groups for this list, so we separate them with a comma in the groupsIDs
parameter.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs> <ws:groupsIDs>22;13<,23</ws:groupsIDs> <!--Add to list 1 (no group) and to list 2 (no group). A semicolon has to be specified for groupsIDs field --> <ws:listsIDs>1;2</ws:listsIDs> |
Add recipients to multiple lists (no groups)
In this example, we specify both the listsIDs
and the listsGUIDs
parameters. Each of the parameters must have the same number of elements (separated by semi-colons), so since there are no groups for either list, we include a single semi-colon in the groupsIDs
parameter to denote that there are two elements.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<ws:listsIDs>1;2</ws:listsIDs> <ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs> <ws:groupsIDs>;</ws:groupsIDs> |
...
Add
...
recipients to multiple lists (one group per list)
In this example, we specify both the listsIDs
and the listsGUIDs
parameters. Each of the parameters must have the same number of elements (separated by semi-colons). In this case, we are specifying group 22 for list 1, and group 13 for list 2.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<ws:listsIDs>1;2</ws:listsIDs> <ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs> <!--Use comma to separate groups that belong to the same list and semicolon for groups that belong to different lists--> <ws:groupsIDs>22,23;13</ws:groupsIDs> |
XML structure
It is recommended that you specify the same ordered list for all the recipients to be imported/updated, also including the fields that are not to be set.
...
<ws:groupsIDs>22;13</ws:groupsIDs> |
Add recipients to multiple lists (multiple groups)
In this example, we specify both the listsIDs
and the listsGUIDs
parameters. The first list (ID=1) has two groups (22,23), so we use a comma to separate them in the first element. We then use a semi-colon to denote the second element, since the groupsIDs, listsIDs and listsGUIDs parameters must all have the same number of elements
Code Block | ||
---|---|---|
|
...
<!--Option 1: number and prefix in a single field (use mobileInputType=1)-->
<subscriber email="user@myprovider.com" Prefix="" Number="+0018889624587" Name="">
<!--Option 2: number and prefix in separate fields (use mobileInputType=2)-->
<subscriber email="user@myprovider.com" Prefix="+001" Number="8889624587" Name="">
...
language | html/xml |
---|---|
title | Example of xmlDoc |
firstline | 1 |
linenumbers | true |
collapse | true |
...
| |||||
<ws:listsIDs>1;2</ws:listsIDs>
<ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs>
<ws:groupsIDs>22,23;13</ws:groupsIDs> |
XML Structure
The XML structure for each recipient needs to be consistent for all subscribers, and include empty tags for required values that are empty. When specifying the phone number for a recipient, the structure of your XML must match the mobileInputType
parameter, where either the entire phone number is represented in a single attribute, or the prefix and number are represented in separate attributes.
For example, if the mobileInputType
parameter is set to 1
,use the following XML structure:
Code Block | ||
---|---|---|
| ||
<!--Option 1: number and prefix in a single field (use mobileInputType=1)--> <subscriber email="user@myprovider.com" Prefix="" Number="+0018889624587" Name=""> |
If the mobileInputType
parameter is set to 2
, use the following XML structure:
Code Block | ||
---|---|---|
| ||
<!--Option 2: number and prefix in <campo1>Mike</campo1> <campo2>Brown</campo2> <campo3>Example Consultancy</campo3>separate fields (use mobileInputType=2)--> <subscriber email="user@myprovider.com" Prefix="+001" Number="8889624587" Name=""> |
An example XML subscriber is represented below (note the empty tags for all data fields below 11)
Code Block | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
<subscribers> <subscriber email="mike@example.com" Prefix="" Number="" Name=""> <campo1>Mike</campo1> <campo2>Brown</campo2> <campo4>Los Angeles</campo4> <campo5> <campo3>Example Company</campo3> <campo4>Los Angeles</campo4> <campo5> </campo5> <campo6>90125</campo6> <campo7>CA</campo7> <campo8>US</campo8> <campo9>555 Some <campo8>US</campo8> <campo9>711 NW High St </campo9> Street</campo9> <campo10></campo10> <campo11>555-<campo11>555-123-1234</campo11> </subscriber>subscriber> <!-- repeat for <subscriber email="kevin@example.it" Prefix="" Number="" Name=""> <campo1>Kevin</campo1> <campo2>Durant</campo2> <campo3></campo3> <campo4>Oklahoma City</campo4> <campo5></campo5> <campo6>73102</campo6> <campo7>OK</campo7> <campo8>US</campo8> <campo9>100 West Reno Avenue</campo9> <campo10></campo10> <campo11>1-555-456-4567</campo11> </subscriber> <subscriber email="mary@poppins.com" Prefix="" Number="" Name=""> <campo1>Mary</campo1> <campo2>Poppins</campo2> <campo3></campo3> <campo4>London</campo4> <campo5></campo5> <campo6></campo6> <campo7></campo7> <campo8>UK</campo8> <campo9></campo9> <campo10></campo10> <campo11></campo11> </subscriber> </subscribers> |
Optional fields
Optional fields can be omitted. Numeric values 0 and 1 can be used instead of false and true.
Note |
---|
A 500 Error is returned if they are specified with an empty value (e.g. <asOptOut /> or <asOptOut></asOptOut>). |
...
language | html/xml |
---|---|
title | SOAP request |
linenumbers | true |
collapse | true |
...
each recipient to import -->
</subscribers> |
You can use 0
and 1
in place of true
and false for boolean parameter values.
SOAP Examples
An example SOAP request to StartImportProcesses
:
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.mailupnet.it/"> <soapenv:Header> <ws:Authentication> <ws:User>user</ws:User> <ws:Password>password</ws:Password><ws:encType>UTF-8</ws:encType> </ws:Authentication> </soapenv:Header> <soapenv:Body> <ws:StartImportProcesses> <ws:listsIDs>1</ws:listsIDs> <ws:listsGUIDs>66af9900-xxxx-yyyy-zzzz-beadaf3a3a59</ws:listsGUIDs> <ws:xmlDoc> <subscribers><subscriber email="mike@example.com" Prefix="" Number="" Name=""><campo1>Mike</campo1><campo2>Brown</campo2><campo3>Example Company</campo3><campo4>Los Angeles</campo4><campo5></campo5><campo6>90125</campo6><campo7>CA</campo7><campo8>US</campo8><campo9>711 Some Street</campo9><campo10></campo10><campo11>555-123-1234</campo11></subscriber></subscribers> </ws:xmlDoc> <ws:groupsIDs></ws:groupsIDs> <ws:importType>3</ws:importType> <ws:mobileInputType>1</ws:mobileInputType> <ws:ConfirmEmail>false</ws:ConfirmEmail> <ws:forceOptIn>true</ws:forceOptIn> <ws:asPending>false</ws:asPending> <ws:Authentication> <ws:User>user<asOptOut>false</ws:User> asOptOut> <ws:Password>password<replaceGroups>false</ws:Password><ws:encType>UTF-8</ws:encType> replaceGroups> </ws:Authentication>StartImportProcesses> </soapenv:Header> <soapenv:Body> <ws:StartImportProcesses> <ws:listsIDs>1</ws:listsIDs> <ws:listsGUIDs>66af9900-xxxx-yyyy-zzzz-beadaf3a3a59</ws:listsGUIDs> <ws:xmlDoc> <subscribers> Body> </soapenv:Envelope> |
An example SOAP response returned by StartImportProcess
method. Response may contain more than one process
element, depending on how many lists were specified as input parameters
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Body> <StartImportProcessesResponse xmlns="http://ws.mailupnet.it/"> <StartImportProcessesResult><![CDATA[ <subscriber email="mike@example.com" Prefix="" Number="" Name=""> <?xml version="1.0" encoding="windows-1252" ?> <mailupMessage> <mailupBody> <campo1>Mike</campo1> <ReturnCode>0</ReturnCode> <processes> <process> <campo2>Brown</campo2> <campo3>Example Consultancy</campo3> <processID>69</processID> <listID>1</listID> <ReturnCode>0</ReturnCode> </process> <process> <processID>70</processID> <listID>2</listID> <ReturnCode>0</ReturnCode> </process> </processes> </mailupBody> <campo4>Los Angeles</campo4> <campo5> </campo5> </mailupMessage>]]> </StartImportProcessesResult> </StartImportProcessesResponse> <campo6>90125</campo6> <campo7>CA</campo7> <campo8>US</campo8> <campo9>711 NW High St </campo9> <campo10></campo10> <campo11>555-123-1234</campo11> </subscriber> <subscriber email="kevin@example.it" Prefix="" Number="" Name=""> <campo1>Kevin</campo1> <campo2>Durant</campo2> <campo3></campo3> <campo4>Oklahoma City</campo4> <campo5></campo5> <campo6>73102</campo6> <campo7>OK</campo7> <campo8>US</campo8> <campo9>100 West Reno Avenue</campo9> <campo10></campo10> <campo11>1-555-456-4567</campo11> </subscriber> <subscriber email="mary@poppins.com" Prefix="" Number="" Name=""> <campo1>Mary</campo1> <campo2>Poppins</campo2> <campo3></campo3> <campo4>London</campo4> <campo5></campo5> <campo6></campo6> <campo7></campo7> <campo8>UK</campo8> <campo9></campo9> <campo10></campo10> <campo11></campo11> </subscriber> </subscribers> </ws:xmlDoc> <!--Mandatory fields:--> <ws:groupsIDs></ws:groupsIDs> <ws:importType>3</ws:importType> <ws:mobileInputType>1</ws:mobileInputType> <!--Optional:--> <ws:ConfirmEmail>false</ws:ConfirmEmail> <ws:forceOptIn>true</ws:forceOptIn> <ws:asPending>false</ws:asPending> <ws:asOptOut>false</ws:asOptOut> <ws:replaceGroups>false</ws:replaceGroups> </ws:StartImportProcesses> </soapenv:Body> </soapenv:Envelope> |
Here below you can find an example of the response that is returned by StartImportProcess method. Response may contain more than one "process" item, depending on how many lists were specified as input parameters
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<StartImportProcessesResponse xmlns="http://ws.mailupnet.it/">
<StartImportProcessesResult><![CDATA[
<?xml version="1.0" encoding="windows-1252" ?>
<mailupMessage>
<mailupBody>
<ReturnCode>0</ReturnCode>
<processes>
<process>
<processID>69</processID>
<listID>1</listID>
<ReturnCode>0</ReturnCode>
</process>
<process>
<processID>70</processID>
<listID>2</listID>
<ReturnCode>0</ReturnCode>
</process>
</processes>
</mailupBody>
</mailupMessage>]]>
</StartImportProcessesResult>
</StartImportProcessesResponse>
</soap:Body>
</soap:Envelope> |
Error codes
Error code | Description |
---|---|
-200 | unrecognized error (it is likely that a mandatory parameter is missing) |
-400 | unrecognized error |
-401 | xmlDoc is empty |
-402 | convert xml to csv failed |
-403 | create new import process failed |
-410 | can not create confirmation email |
-450 | listsIDs and listsGUIDs must contain the same number of elements |
-600 | unrecognized error |
-601 | an import process is already running for the list |
-602 | an import process is already running for a different list |
-603 | error checking process status |
-604 | error starting the process job |
Code examples
Ruby Example
Code Block | ||
---|---|---|
| ||
# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mailup'
m = MailUp::Import.new('username', 'password', 'console_url')
m.start_import_processes(:listsIDs => "1;2;3, :listsGUIDs => "abc123;def456;ghi789, :xmlDoc => "XML_STRING", ...)
# => <?xml version=\"1.0\" encoding=\"windows-1252\" ?><mailupMessage><mailupBody><ReturnCode>0</ReturnCode><processes>...</processes></mailupBody></mailupMessage> |
PHP Example
...
language | php |
---|---|
linenumbers | true |
collapse | true |
...
</soap:Body>
</soap:Envelope> |
Error codes
Below is a list of the ReturnCode
values, and what they mean when an error is encountered.
Error code | Description |
---|---|
-200 | unrecognized error (it is likely that a mandatory parameter is missing) |
-400 | unrecognized error |
-401 | xmlDoc is empty |
-402 | convert xml to csv failed |
-403 | create new import process failed |
-410 | can not create confirmation email |
-450 | listsIDs and listsGUIDs must contain the same number of elements |
-600 | unrecognized error |
-601 | an import process is already running for the list |
-602 | an import process is already running for a different list |
-603 | error checking process status |
-604 | error starting the process job |
Code Examples
The code examples below are provided on an "as is" basis, without any warranty of any kind. MailUp shall not be held liable for any direct, indirect or consequential damages or costs of any type arising out of any action taken by you or other related to the example code. Please contact us if you are interested in submitting examples for programming languages that are not already included below.
Ruby
Code Block | ||
---|---|---|
| ||
# Refer to https://mailup.atlassian.net/wiki/display/mailupapi/MailUp+RubyGem for gem information.
require 'mail up'
m = MailUp::Import.new('username', 'password', 'console_url')
m.start_import_processes(
listsIDs: "1;2;3",
listsGUIDs: "abc123;def456;ghi789",
xmlDoc: xml_data_string,
groupsIDs: '',
importType: 3,
mobileInputType: 1
)
# => <?xml version=\"1.0\" encoding=\"windows-1252\" ?><mailupMessage><mailupBody><ReturnCode>0</ReturnCode><processes>...</processes></mailupBody></mailupMessage> |
PHP
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
<?php class MailUpWsImport { protected $ns = "http://ws.mailupnet.it/"; |
...
//replace <console host name> with the host name of your console |
...
protected $WSDLUrl = "http://<console host name>/services/WSMailUpImport.asmx?WSDL"; |
...
protected $headers = array("User" => "user", "Password" => "password");
|
...
protected $rCode; |
...
private $soapClient; |
...
private $xmlResponse; |
...
protected $domResult; |
...
function __construct() {
|
...
$this->header = new SOAPHeader($this->ns, "Authentication", $this->headers); |
...
$this->soapClient = new SoapClient($this->WSDLUrl,array("trace" => 1,"exceptions" => 0)); |
...
$this->soapClient->__setSoapHeaders($this->header); |
...
} |
...
|
...
function __destruct() { |
...
unset($this->soapClient); |
...
}
|
...
...
//...
|
...
public function startImportProcesses($processData) { |
...
try { |
...
echo $processData."<br/><br/>"; |
...
$this->soapClient->StartImportProcesses($processData); |
...
} catch (SoapFault $soapFault) { |
...
var_dump($soapFault); |
...
} |
...
} |
...
|
...
//... } $WsImport = new MailUpWsImport(); |
...
$xmlData = <<<EOT <subscribers><subscriber email="test@example.com" Prefix="+39" Number="3351234567" Name="Test"> <campo1>Luigi</campo1><campo2>Rossi</campo2><campo3>Rossi consulting</campo3><campo4>Parma2</campo4><campo5>PR</campo5> <campo6>43102</campo6><campo7></campo7><campo8>ITA</campo8><campo9>Via Garibaldi, 1</campo9><campo10>0521123456</campo10> <campo11>0521123457</campo11></subscriber></subscribers> EOT; $startImportProcessData = array( "listsIDs" => "4", |
...
"listsGUIDs" => "3c5cb08c-f0b5-4bd6-9c2a-b687ecdac8b4", |
...
"xmlDoc" => $xmlData, |
...
"groupsIDs" => "22",
|
...
"importType" => "3", |
...
"mobileInputType" => "2", |
...
"asPending" => '0',
|
...
"ConfirmEmail" => "0", |
...
"asOptOut" => "0", |
...
"forceOptIn" => "0", |
...
"replaceGroups" => "0" ); |
...
$WsImport->startImportProcesses($startImportProcessData); ?> |
...
...