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 signature
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
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.
- listsIDs: list identifiers (even more than one, comma separated)
- listsGUIDs: GUID of the list (even more than one, comma separated)
- xmlDoc: XML string containing the recipients to be imported (see paragraph "XML structure" below)
- groupsIDs: group identifiers separated by comma (more than a group for each list is possible).
- importType: import type (default value=3)
- mobileInputType: mobile number input type (see paragraph "XML feed" below)
- 1= include international code
- 2=international code and phone number in two different fields
- asPending: subscribes users as pending, if true (default value=false)
- ConfirmEmail: sends confirmation request email (default value=false). When "true" the system will then automatically create a confirmation newsletter based on a default template.
- asOptOut: imports users as unsubscribed (default value=false)
- forceOptIn: forces subscription of recipients(default value=false), even when updating unsubscribed recipients.
- replaceGroups: replaces groups (default value=false). When "true" the system will then automatically remove previously subscribed groups and keeps only the settings specified in "groupsIDs" field.
Below you can find details and examples.
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.
<!--listsIDs, listsGUIDs and groupsIDs shall always be arrays with the same length (even when fields are empty)-->
<!--Add to list 1 (no groups, both ID and GUID are specified)-->
<ws:listsIDs>1</ws:listsIDs>
<ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs>
<ws:groupsIDs></ws:groupsIDs>
<!--Add to list 1 (group 22, only list ID is specified)-->
<ws:listsIDs>1</ws:listsIDs>
<ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs>
<ws:groupsIDs>22</ws:groupsIDs>
<!--Add to list 1 (groups 22 and 23, only list GUID is specified)-->
<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>
<!--Add to list 1 (group 22) and to list 2 (group 13)-->
<ws:listsIDs>1;2</ws:listsIDs>
<ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs>
<ws:groupsIDs>22;13</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>
<ws:listsGUIDs>66af9900-7dd7-4cca-9125-beadaf3a3a59;0e591119-xxxx-yyyy-zzzz-6ac75384b564</ws:listsGUIDs>
<ws:groupsIDs>;</ws:groupsIDs>
<!--Add to list 1 (groups 22 and 23) and to list 2 (group 13). GUID is not specified-->
<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.
Phone numbers are to be specified in the same format for all recipients in xmlDoc parameter using one of the following options:
<!--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="">
An example of XML structure for importing subscribers is shown here:
<subscribers>
<subscriber email="mike@example.com" Prefix="" Number="" Name="">
<campo1>Mike</campo1>
<campo2>Brown</campo2>
<campo3>Example Consultancy</campo3>
<campo4>Los Angeles</campo4>
<campo5> </campo5>
<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>
Optional fields
Optional fields can be omitted. Numeric values 0 and 1 can be used instead of false and true.
SOAP Examples
<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 Consultancy</campo3>
<campo4>Los Angeles</campo4>
<campo5> </campo5>
<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
<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
# 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
<?php
// The sample code described herein is provided on an "as is" basis, without warranty of any kind.
// MailUp shall not be liable for any direct, indirect or consequential damages or costs of any type arising out of any action taken by you or others related to the sample code.
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);
?>