List unsubscribers address book

The ListUnsubscribersAddressBook method retrieves a list of contacts that were created on or after a given dateTime.

Guidance Notes

You may request up to 1000 records at a time. To iterate through the whole data set you should use the select and skip parameters. For example to select the first 1000 records in the data set you should set the select parameter to 1000 and the skip parameter to 0. To select the next 1000 records you should set the select parameter to 1000 and the skip parameter to 1000. You should continue to do this until 0 records are returned to you to get the whole data set.

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
startDate	dateTime	The date from which you wish to query.	required
addressBookId	int	This is the ID of the addressbook you want to query against.	required
select	int	This is a number which indicates the number of records you wish to select. This argument must no greater than 1000	required
skip	int	This is a number which is the number of records you want to skip; to select all records from 1001 to 2000: set this number to 1000.	required

Return values

The result is an array of contact objects.

Error responses

ERROR_APIUSAGE_EXCEEDED
ERROR_INVALID_LOGIN
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/ListUnsubscribersAddressBook"

Example of use in C# .NET

/// <summary>
/// This method can be used to get a list of contacts who have unsubscribed 
/// from a particular address book in your dotMailer account after a given date. 
/// </summary>
public void ListUnsubscribersAddressBook()
{
    const string username = "apiuser-XXXXXXXXXXXX@apiconnector.com";
    const string password = "password";
    const int addressBookId = 1;
 
    Console.WriteLine("ListUnsubscribersAddressBook");
    Console.WriteLine("----------------------------");
 
    // Get an instance to the web reference
    com.apiconnector.API api = new com.apiconnector.API();
 
    try
    {
        int currentPage = 0;   // what page are we on
        const int itemsPerPage = 20;  // the number of campaigns we want to be returned for each page
 
        // we are interested in the last 30 days
        DateTime startDate = DateTime.Now - new TimeSpan(30, 0, 0, 0);
 
        // execute the first get from the server
        // the select parameter is the itemsperPage, 
        // the skip is the itemsPerPage * the currentPage
        com.apiconnector.APIContact[] contacts = api.ListUnsubscribersAddressBook(username, password, startDate, addressBookId, itemsPerPage, currentPage * itemsPerPage);
 
        // keep getting displaying and getting more contacts until we have no more
        while (contacts != null && contacts.Length > 0)
        {
            // output the current page
            Console.WriteLine("CurrentPage: {0}", currentPage + 1);
 
            foreach (com.apiconnector.APIContact contact in contacts)
            {
                Console.WriteLine("AudienceType : {0}", contact.AudienceType);
                Console.WriteLine("Email : {0}", contact.Email);
                Console.WriteLine("EmailType : {0}", contact.EmailType);
                Console.WriteLine("ID : {0}", contact.ID);
                Console.WriteLine("Notes : {0}", contact.Notes);
                Console.WriteLine("OptInType : {0}", contact.OptInType);
 
                // write out blank line, so the output is easier to read
                Console.WriteLine();
            }
 
            // increment the page
            currentPage++;
 
            // execute the next get - see above
            contacts = api.ListUnsubscribersAddressBook(username, password, startDate, addressBookId, itemsPerPage, currentPage * itemsPerPage);
        }
 
        // output some stats
        Console.WriteLine("Total Pages {0}, {1} per page", currentPage, itemsPerPage);
        Console.WriteLine();
    }
    catch (SoapException ex)  // catch any soap issues/errors from the web service
    {
        Console.WriteLine("Error -> {0}", ex.Message);
    }
 
    Console.WriteLine();     
}

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/ListUnsubscribersAddressBook"
<?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>
    <ListUnsubscribersAddressBook xmlns="http://apiconnector.com">
      <username>string</username>
      <password>string</password>
      <startDate>dateTime</startDate>
      <addressBookID>int</addressBookID>
      <select>int</select>
      <skip>int</skip>
    </ListUnsubscribersAddressBook>
  </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>
    <ListUnsubscribersAddressBookResponse xmlns="http://apiconnector.com">
      <ListUnsubscribersAddressBookResult>
        <APIContact>
          <ID>int</ID>
          <Email>string</Email>
          <AudienceType>Unknown or B2C or B2B or B2M</AudienceType>
          <DataFields>
            <Keys xsi:nil="true" />
            <Values xsi:nil="true" />
          </DataFields>
          <OptInType>Unknown or Single or Double or VerifiedDouble</OptInType>
          <EmailType>PlainText or Html</EmailType>
          <Notes>string</Notes>
        </APIContact>
        <APIContact>
          <ID>int</ID>
          <Email>string</Email>
          <AudienceType>Unknown or B2C or B2B or B2M</AudienceType>
          <DataFields>
            <Keys xsi:nil="true" />
            <Values xsi:nil="true" />
          </DataFields>
          <OptInType>Unknown or Single or Double or VerifiedDouble</OptInType>
          <EmailType>PlainText or Html</EmailType>
          <Notes>string</Notes>
        </APIContact>
      </ListUnsubscribersAddressBookResult>
    </ListUnsubscribersAddressBookResponse>
  </soap:Body>
</soap:Envelope>

Prebuilt integrations

More about API

Address books

Contacts

Campaigns

Reporting

SMS

Account

Images

Documents

Templates