Add contact to address book

The AddContactToAddressBook method is designed to add a single contact into an address book. It allows you to set information about the contact which you are uploading and specify the address book you are uploading them to.

This method is useful when you are building a newsletter signup or registration process when you also require the data to be used in another way (e.g. add the contact to a CRM system). If you just want to add a contact, then please review our "Contact Data Forms" feature within the app for a much easier approach. Any contacts added via this method will fire any join action that has been defined on an address book.

Guidance Notes

This method will create the contact required if it doesn't already exist within the dotMailer system. This means that calling a method such as CreateContact prior to the use of this method is unnecessary. If the contact does already exist within the dotMailer account we will assume that the information you are uploading is the most recent and therefore correct information. This means that we will overwrite any existing information associated with this contact in the dotMailer system with the information in this upload; even if it means the contact will have blank data associated with it.

If you are going to be uploading multiple contacts please use AddContactsToAddressBook or AddContactsToAddressBookWithProgress which allow you to upload multiple contacts in a single API call.

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
contact	contact	This is the contact object; the only required property of the contact object is the email address.	partially required
addressBookId	int	This is the ID of the address book that you wish to add the contact to.	required

Return values

contact

This is a contact object; it includes the generated ID.

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_INVALID_EMAIL
ERROR_INVALID_LOGIN
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/AddContactToAddressBook"

Example of use in C#

/// <summary>
/// Adds a contact to an address book
/// </summary>
public void AddContactToAddressBook() 
{
    const string username = "apiuser-XXXXXXXXXXXX@apiconnector.com";
    const string password = "password";
    const int addressBookId = 1;  // ID of the target address book
 
    Console.WriteLine("AddContactToAddressBook");
    Console.WriteLine("-----------------------");
 
    // Get an instance to the web reference
    com.apiconnector.API api = new com.apiconnector.API();
 
    try
    {
        // we need a new contact
        com.apiconnector.APIContact contact = new com.apiconnector.APIContact();
        
        // populate the contact
        contact.AudienceType = com.apiconnector.ContactAudienceTypes.B2B;
 
        // populate the data fields
        contact.DataFields = new com.apiconnector.ContactDataFields();
        contact.DataFields.Keys = new string[3];
        contact.DataFields.Values = new object[3];
 
        contact.DataFields.Keys[0] = "FIRSTNAME";
        contact.DataFields.Values[0] = "John";
        contact.DataFields.Keys[1] = "LASTNAME";
        contact.DataFields.Values[1] = "Smith";
        contact.DataFields.Keys[2] = "POSTCODE";
        contact.DataFields.Values[2] = "IP4 1XU";
        
 
        // email address
        contact.Email = "joe.smith@example.com";
 
        contact.EmailType =  com.apiconnector.ContactEmailTypes.PlainText;
        contact.Notes = "This is a test only email";
        contact.OptInType = com.apiconnector.ContactOptInTypes.Single;
 
        // This method will create the contact required if it doesn't already exist within the dotMailer system,
        // so we don't have to call CreateContact as a prerequisite.
        // 
        // This method will also overwrite an existing contact, with the information provided here.
        //
        // This method will fail if you try to add a contact to the "Test" or "All Contacts" address books.
        //
        com.apiconnector.APIContact newContact = api.AddContactToAddressBook(username, password, contact, addressBookId);
 
        // Did we get something back from the API ?
        if (newContact != null)
        {
            Console.WriteLine("Contact added to address book {0} -> {1}", newContact.ID, addressBookId);
        }
    }
    catch (SoapException ex)  // catch any soap issues/errors from the web service
    {
        Console.WriteLine("Error -> {0}", ex.Message);                
    }
 
    Console.WriteLine();
}

Example of use in VB.NET

''' <summary>
''' Adds a contact to an address book
''' </summary>
Public Sub AddContactToAddressBook()
    Const username As String = "apiuser-XXXXXXXXXXXX@apiconnector.com"
    Const password As String = "password"
    Const addressBookId As Integer = 1
    ' ID of the target address book
    Console.WriteLine("AddContactToAddressBook")
    Console.WriteLine("-----------------------")
    ' Get an instance to the web reference
    Dim api As New com.apiconnector.API()
    Try
	' we need a new contact
	Dim contact As New com.apiconnector.APIContact()
	' populate the contact
	contact.AudienceType = com.apiconnector.ContactAudienceTypes.B2B
	' populate the data fields
	contact.DataFields = New com.apiconnector.ContactDataFields()
	contact.DataFields.Keys = New String(2) {}
	contact.DataFields.Values = New Object(2) {}
	contact.DataFields.Keys(0) = "FIRSTNAME"
	contact.DataFields.Values(0) = "John"
	contact.DataFields.Keys(1) = "LASTNAME"
	contact.DataFields.Values(1) = "Smith"
	contact.DataFields.Keys(2) = "POSTCODE"
	contact.DataFields.Values(2) = "IP4 1XU"
	' email address
	contact.Email = "joe.smith@example.com"
	contact.EmailType = com.apiconnector.ContactEmailTypes.PlainText
	contact.Notes = "This is a test only email"
	contact.OptInType = com.apiconnector.ContactOptInTypes.[Single]
	' This method will create the contact required if it doesn't already exist within the dotMailer system,
	' so we don't have to call CreateContact as a prerequisite.
	' 
	' This method will also overwrite an existing contact, with the information provided here.
	'
	' This method will fail if you try to add a contact to the "Test" or "All Contacts" address books.
	'
	Dim newContact As com.apiconnector.APIContact = api.AddContactToAddressBook(username, password, contact, addressBookId)
	' Did we get something back from the API ?
	If newContact IsNot Nothing Then
	    Console.WriteLine("Contact added to address book {0} -> {1}", newContact.ID, addressBookId)
	End If
    Catch ex As SoapException
	' catch any soap issues/errors from the web service
	Console.WriteLine("Error -> {0}", ex.Message)
    End Try
    Console.WriteLine()
End Sub

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 add a new contact, testemail@test.co.uk , and populate the firstname, lastname and age datafields
  
  
  
  $addressbookid=469226;
  $email = "testemail@test.co.uk";
  $AudienceType="B2B";
  $OptInType="Single";
  $EmailType="Html";
  $FirstName = "John";
  $LastName="Test";
  $Age = 35;
  $notes = "This is an API test contact" ;
  
  $keys = array("FIRSTNAME","LASTNAME","AGE");
  $var1 = new SoapVar($FirstName,XSD_STRING,"string","http://www.w3.org/2001/XMLSchema"); //Create an instance of SoapVar for each one of the values
  $var2 = new SoapVar($LastName,XSD_STRING,"string","http://www.w3.org/2001/XMLSchema");
  $var3 = new SoapVar($Age,XSD_INT,"int","http://www.w3.org/2001/XMLSchema");
  $values = array($var1,$var2,$var3);
  $Datafields = array ('Keys'=>$keys,'Values'=>$values);
  $contact = array ("Email"=>$email,"AudienceType"=>$AudienceType,"OptInType"=>$OptInType,"EmailType"=>$EmailType,"ID"=>-1,"DataFields"=>$Datafields,"Notes"=>$notes);
  $params = array ("username"=>$username,"password"=>$password,"contact"=>$contact,"addressbookId"=>$addressbookid);
  return $client->AddContactToAddressbook($params);
  
  
?>

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/AddContactToAddressBook"
<?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>
      <AddContactToAddressBook xmlns="http://apiconnector.com">
         <username>string</username>
         <password>string</password>
         <contact>
            <ID>int</ID>
            <Email>string</Email>
            <AudienceType>Unknown or B2C or B2B or B2M</AudienceType>
            <DataFields>
               <Keys>
                  <string>string</string>
                  <string>string</string>
               </Keys>
               <Values>
                  <anyType xsi:type="xsd:string">string</anyType>
                  <anyType xsi:type="xsd:int">int</anyType>
               </Values>
            </DataFields>
            <OptInType>Unknown or Single or Double or VerifiedDouble</OptInType>
            <EmailType>PlainText or Html</EmailType>
            <Notes>string</Notes>
         </contact>
         <addressbookId>int</addressbookId>
      </AddContactToAddressBook>
   </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>
    <AddContactToAddressBookResponse xmlns="http://apiconnector.com">
      <AddContactToAddressBookResult>
        <ID>int</ID>
        <Email>string</Email>
        <AudienceType>Unknown or B2C or B2B or B2M</AudienceType>
        <DataFields>
          <Keys>
            <string>string</string>
            <string>string</string>
          </Keys>
          <Values>
            <anyType />
            <anyType />
          </Values>
        </DataFields>
        <OptInType>Unknown or Single or Double or VerifiedDouble</OptInType>
        <EmailType>PlainText or Html</EmailType>
        <Notes>string</Notes>
      </AddContactToAddressBookResult>
    </AddContactToAddressBookResponse>
  </soap:Body>
</soap:Envelope>

Prebuilt integrations

More about API

Address books

Contacts

Campaigns

Reporting

SMS

Account

Images

Documents

Templates