Add contacts to address book with progress

The AddContactsToAddressBookWithProgress method allows you to add multiple contacts to an address book within the dotMailer system. It allows you to track the progress of the import by returning a GUID which you can use to query the import progress.

This method is useful when you need to upload multiple contacts in one go into the dotMailer system. As each call only counts as one API call it allows you to easily stay below your API limit whilst uploading multiple contacts. It has the benefit of being run through our data watchdog so you know the data you are importing is of a good quality.

It will return a GUID which you can use to check the progress of your import. This is useful if you want to perform an action on the address book when the import has finished.

Guidance Notes

This method will create the contact being added if it doesn't already exist which means you do not need to call a method such as CreateContact before calling it. You may upload either a .csv or .xls file. It must contain one column with the heading "Email" or the translated equivalent if your account is using a language other than English. Other columns will attempt to map to your custom data fields. There is a 10MB file upload limit; if your file is larger than this, please break your upload into separate files.

As the import goes through our data watchdog there might be a delay between uploading the contacts and them being successfully added to the address book.

To query the progress of the import please call GetContactImportProgress using the GUID returned by AddContactsToAddressBookWithProgress.

Parameters

username	string	This is the username from your API key. It is in the format of an email address and will look similar to apiuser-908709770324@apiconnector.com	required
password	string	This is the password from your API key.	required
addressBookId	int	This is the ID of the address book which you would like to upload the contacts to.	required
data	base64Binary	This is the original file, encoded in Base64 format.	required
dataType	CSV or XLS	This is the type of file which you are uploading, either .CSV, or .XLS. At this time, XLSX is not supported.	required

Return values

progressid

guid

The guid used to call GetContactImportProgress

Error responses

ERROR_ADDRESSBOOK_NOT_FOUND
ERROR_ADDRESSBOOK_NOTWRITABLE
ERROR_APIUSAGE_EXCEEDED
ERROR_CONTACT_INVALID
ERROR_CONTACT_SUPPRESSED
ERROR_CONTACT_TOOMANY
ERROR_DATAFIELD_NOTFOUND
ERROR_IMPORT_TOOMANYACTIVEIMPORTS
ERROR_INVALID_LOGIN
ERROR_NO_EMAIL_COLUMN
ERROR_PARAMETER_INVALID
ERROR_SYSTEM_SERVICETEMPORARILYUNAVAILABLE
ERROR_UNKNOWN

Request

POST /API.asmx HTTP/1.1
Host: apiconnector.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://apiconnector.com/AddContactsToAddressBookWithProgress"

Example of use in C#

/// <summary>
/// This method allows you to add multiple contacts to an address book within
/// the dotMailer system. It allows you to track the progress of the import by
/// returning a GUID which you can use to query the import progress.
///
/// Tracking the import progress uses GetContactImportprogress
/// </summary>
public void AddContactsToAddressBookWithProgress()
{
const string username = "apiuser-XXXXXXXXXXXX@apiconnector.com";
const string password = "password";
const int addressBookId = 1;  // ID of the target address book
const string sourceFileName = "Contacts.CSV";
const int readSize = 10 * 1024;       // aim to read in 10Kb at a time from the source file (example file is ~920Kb)
Guid importGuid = Guid.Empty;   // the guid given to us by the web service, which allows us to track the progress of the import
Console.WriteLine("AddContactsToAddressBookWithProgress");
Console.WriteLine("-----------------------------------");
// Get an instance to the web reference
com.apiconnector.API api = new com.apiconnector.API();
try
{
byte[] buffer;
// first step is to read the source file into memory
using (BinaryReader br = new BinaryReader(File.Open(sourceFileName, FileMode.Open, FileAccess.Read)))
{
// how much data are we going to read
long totalLength = br.BaseStream.Length;
long read = 0;
// we need somewhere to put our file data
buffer = new byte[totalLength];
while (read != totalLength)
{
byte[] temp = br.ReadBytes(readSize);
int amountRead = temp.Length;
// copy over the amount of data we have read into our
// main buffer
for (int i = 0; i < amountRead; i++)
{
buffer[read + i] = temp[i];
}
// update the amount of data we have read
read += amountRead;
}
// close the stream - we are done with it.
br.Close();
}
//
// We have a buffer of bytes that contains the file data,
// so we can now upload this to the server via the web service
//
// The source file that was used is CSV, if this is changed to XLS, then the
// ImportDataType should be changed
//
importGuid = api.AddContactsToAddressBookWithProgress(username, password, addressBookId, buffer, com.apiconnector.ImportDataType.CSV);
// get the first import status
com.apiconnector.ImportStatus importStatus = api.GetContactImportProgress(username, password, importGuid);
// wait until the import status is finished
while (importStatus == com.apiconnector.ImportStatus.NotFinished )
{
// indicate that we are still doing something
Console.Write(".");
// get the import status
importStatus = api.GetContactImportProgress(username, password, importGuid);
//
// send the current thread to sleep - this prevents us _constantly_ asking for import status updates
// and will allow the web server to do some work
//
System.Threading.Thread.Sleep(1000);
}
Console.WriteLine();
// output the final state of the import process
switch (importStatus)
{
case com.apiconnector.ImportStatus.Finished:
Console.WriteLine("Contact Import process completed.");
break;
case com.apiconnector.ImportStatus.InvalidFileFormat:
Console.WriteLine("Contact Import process failed - there was a problem with the file format.");
break;
case com.apiconnector.ImportStatus.RejectedByWatchdog:
Console.WriteLine("Contact import process failed - one or more contacts rejected by Watchdog.");
break;
case com.apiconnector.ImportStatus.Unknown:
Console.WriteLine("Contact import process failed - Unknown Error");
break;
}
// if we are still here - we are all done
Console.WriteLine("Imported data from file [{0}]", sourceFileName);
}
catch (SoapException ex)  // catch any soap issues/errors from the web service
{
Console.WriteLine("Error -> {0}", ex.Message);
}
Console.WriteLine();
}

Example of use in PHP

<?php
$username = "APIUsernameHere"; //Your API username
$password = "***********";  //your API password
$client = new SoapClient("http://apiconnector.com/api.asmx?WSDL"); //Instantiate the Soap client
//We will upload the Contactslist.csv  file to the system.Import token will be returned
$file =  'Contactslist.csv' ;
$handler = fopen($file,'r') ; //create a handler
$readfile = fread($handler,filesize($file)); // read the contents of the file
$encoded = base64_encode($readfile); //encode the file contents in base64 format
$typedVar = new SoapVar($encoded,XSD_BASE64BINARY,"string","http://www.w3.org/2001/XMLSchema"); //Declare the type as BASE64Binary    string
$addressbookid=469226;
$datatype = "CSV";
$params = array("username"=>$username,
"password"=>$password,
"addressbookID"=>$addressbookid,
"data"=>$typedVar,
"dataType"=>$datatype ) ;
$client->AddContactsToAddressBookWithProgress($params);
$import = $client->AddContactsToAddressBookWithProgress($params);
echo $import->AddContactsToAddressBookWithProgressResult; //Retrieve the import token (can be used eith the  GetContactImportProgress to query import progress)
?>

Sample request

POST /API.asmx HTTP/1.1
Host: apiconnector.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://apiconnector.com/AddContactsToAddressBookWithProgress"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<AddContactsToAddressBookWithProgress xmlns="http://apiconnector.com">
<username>string</username>
<password>string</password>
<addressbookID>int</addressbookID>
<data>base64Binary</data>
<dataType>CSV or XLS</dataType>
</AddContactsToAddressBookWithProgress>
</soap:Body>
</soap:Envelope>

Sample response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<AddContactsToAddressBookWithProgressResponse xmlns="http://apiconnector.com">
<AddContactsToAddressBookWithProgressResult>guid</AddContactsToAddressBookWithProgressResult>
</AddContactsToAddressBookWithProgressResponse>
</soap:Body>
</soap:Envelope>

About the API

Address books

Contacts

Campaigns

Reporting

SMS

Account

Images

Documents

Templates