Contents

• Introduction
• Webservice location
• Methods
  • Method: addr_search
  • Method: address_search
  • Method: address_search_as
• Data Types
  • Data Type: LookupResult
  • Data Type: NVP
  • Data Type: SearchResult
• Example Clients and wiredump

Introduction

A SOAP (Simple Object Access Protocol) webservice is available for email address searches and is described below.

Webservice location

English descriptions of the methods and data types are lower down the page.

Note: you must use the lowercase domain name otherwise the webserver will issue a "301" redirect which can frustrate some SOAP clients.

Methods

Method: addr_search

SearchResult addr_search(string, string, ArrayOfstring)

1. key:string - the 32 character "Search License Key" found in the the user's account
2. encoding:string - currently one of
   • md5
   • plaintext
   This describes the encoding type for the email addresses passed in the third argument. Although SSL encryption is available for SOAP access it is still recommended that email addresses are encoded.
3. emails:array - a simple array of email addresses, either md5 encoded or plaintext, to query against the database.

The method returns one argument, a SearchResult structure

jo.bloggs@example.com

Jo.Bloggs@example.com
Jo Bloggs <jo.bloggs@example.com>
"Jo Bloggs" <jo.bloggs@example.com>
etc.

Method: address_search

Deprecated

array address_search(int, int, int, string, array)

This method takes five arguments:

1. id: int - Your account number
2. v1: int - The first part of your license string
3. v2:int - The second part of your license string
4. encoding:string - either the string ‘plaintext’ or ‘md5’ (without the quote marks)
5. emails:array - a simple array of email addresses to query against the database.

The method returns one argument: an array of LookupResult structs, one for each address in the query array.

If you give ‘md5’ as the 4th argument then each address in the query array should be encoded using the MD5 message digest algorithm.

Method: address_search_as

Deprecated

array address_search_as(int, int, int, string, array, string)

1. id:int - Your account number
2. v1:int - The first part of your license string
3. v2:int - The second part of your license string
4. encoding:string - either the string ‘plaintext’ or ‘md5’ (without the quote marks)
5. emails:array - a simple array of email addresses to query against the database.
6. search_as:string - the email address of the user you’re searching on behalf of.

The method returns one argument: an array of LookupResult structs, one for each address in the query array.

If you give ‘md5’ as the 4th argument then each address in the query array should be encoded using the MD5 message digest algorithm.

This method is identical to address_search above except for the extra 6th argument. If you hold a number of address books for various users, e.g. if you are an email provider, then you can use this method to spring-clean each address book on behalf of the user. In which case you should supply the address-book user’s email address as the 6th argument.

Data Types

Data Type: LookupResult

query

string

result

string

The values returned in the result field are one of:

1. the target's preferred email address. Note this could be the same as the query address.
2. the string noforward if the target is registered with ContactClean but hasn't confirmed their forwarding address yet.
3. the string norecord if there is no record of the target on the system, or if they have not given their permission for their new address details to be released.
4. the string remove if the target wishes to be removed from your address list!

The type ArrayOfLookupResult is an anonymous array of LookupResult structs

Data Type: NVP

name

string

value

string

The type ArrayOfNVP is an anonymous array of NVP structs

Data Type: SearchResult

search_result

ArrayOfLookupResult

report

ArrayOfNVP

Example clients