Page tree
Skip to end of metadata
Go to start of metadata

Introduction

DOTS Email Validation 3 (EV3) is a web service that provides validity and metadata information about an email address. The service provides common data elements such as syntax validity along with more refined data such as SMTP failures and deliverability flags. 

EV3 can help provide instant email data verification to websites or enhancement to contact lists.

If you are an existing client and are using the previous version of this service then please click on the following link.

DOTS Email Validation 2

Overview of How it Works

These are the essential checks that are performed by each operation. The service operation steps through each section to determine if an email is valid. If one step fails, subsequent checks are not made because they have been logically eliminated. Example: if the syntax on an email fails, neither the DNS nor the SMTP check is done.

Step 1: Email Correction - The email is first cleaned and corrected before being validated and verified. Extraneous text and characters are removed and common email deformities are fixed. Typos, misspellings as well as incomplete domains are also corrected.

Step 2: Syntax Check - The email is tested to verify that the format is valid, such as an "@" symbol, a domain, and no odd characters that aren't allowed in email addresses. The rules specific to the domain are also checked. For example, if you input aa@aol.com it will pass the syntax check but fail the domain specific syntax check, and therefore we do not need to continue with the DNS or SMTP level checks.

Step 3: DNS Check - The DNS or domain name check verifies that the domain exists and has a valid MX record in order to relay mail.

Step 4: SMTP Check - Once we obtain the location of the mail server from a successful DNS check, we start communicating with the target mail server. No email is actually sent to the email address being verified. This step gives us three pieces of information. It tells us if the server is working, if it will accept any address, and if will it accept this specific address. One difficulty of email validation is dealing with the defensive behaviors of email servers. Because of the growth of spam and email-mining tools, SMTP servers often respond to requests for information in cryptic and defensive ways. Mail servers may respond very slowly to information requests, provide unhelpful data, or sometimes no data at all. We have carefully crafted our system with this in mind, and therefore the data we return is still very accurate. However, sometimes we are still forced to return an unknown result for some of the SMTP level checks.

Step 5: Integrity Checks - A deliverable email address is not always a good email address. Just because an email does not bounce back does not mean that it was received, and so our service performs a variety tests and checks to evaluate the integrity of an email address. For example an email address may be a disposable address that is only temporarily deliverable or worst yet a spam trap.

Integration

Integrating EV3 into your application should be easy and straightforward. If you are using a common platform, such as asp, vb, C# .NET, PHP and others, Service Objects may already have sample code built that you can use.

However, if you are using a common platform that does not already have sample code, you can ask Service Objects to build an example for you. Email support@serviceobjects.com for more details.

Web Service Structure

Web services provide a standard interface to encapsulate tricky business logic. They allow simple integration of applications via the web. Service Objects has followed web services best practices and come up with some of its own standards to ensure that its web services are as easy to integrate, and as accessible as possible.

The host path, or physical location of the web service is here:
https://trial.serviceobjects.com/ev3/web.svc

A test page for the web service can be found here:
https://trial.serviceobjects.com/ev3/

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
https://trial.serviceobjects.com/ev3/soap.svc?wsdl

Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

The WSDL is an XML document that defines the interaction web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application via some type of proxy class. Whenever your utilities or IDE asks for a WSDL path, you can provide this one. Every web service has operations that it offers to subscribers. These operations, also called methods, contain different functionality and return different outputs.

Code Snippets




Email Validation 3 C# Code Snippet
EV3LibraryClient EV3Client_Backup = null;
ValidateEmailResponse response = null;

try
{
	EV3Client_Primary = new EV3LibraryClient("DOTSEV3PRIMARY");
	EV3Client_Primary.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
	response = EV3Client_Primary.ValidateEmailAddress(EmailAddress, AllowCorrection, Timeout, LicenseKey);///EQUATE TO RESPONSE
	//NULL ERROR || FATAL ERROR RETURNE -- TRY BACKUP
	if (response == null || (response.Error != null && response.Error.TypeCode == "3"))
	{
		throw new Exception();
	}
	return response;
}
catch (Exception e)
{
	try
	{
		EV3Client_Backup = new EV3LibraryClient("DOTSEV3BACKUP");
		EV3Client_Backup.InnerChannel.OperationTimeout = new TimeSpan(0, 0, 0, WEB_SERVICE_REQUEST_TIMEOUT);
		return EV3Client_Backup.ValidateEmailAddress(EmailAddress, AllowCorrection, Timeout, LicenseKey);
	}
	catch (System.Exception ex)
	{
		throw ex;
	}
	finally
	{
		if (EV3Client_Backup != null) { EV3Client_Backup.Close(); }
	}
}


Email Validation 3 Java Code Snippet
try{

		
	ValidateEmailResponse resp = null;
	ValidateEmailInfo result = null;
	Error error = null;
	String email = request.getParameter("iEmail");
	String allowcorrections = request.getParameter("iAllowCorrections");//
	String timeout = request.getParameter("iTimeout");//
	String key = request.getParameter("iKey");
	
	// Create soap request
	EV3LibraryLocator locator = new EV3LibraryLocator();
	// use ssl
	locator.setDOTSEmailValidation3EndpointAddress("https://trial.serviceobjects.com/ev3/soap.svc/soap");
	IEV3Library ev3 = locator.getDOTSEmailValidation3();
	DOTSEmailValidation3Stub soap = (DOTSEmailValidation3Stub)ev3;
	soap.setTimeout(5000);// set timeout
	try{
	
		resp = soap.validateEmailAddress(email, allowcorrections, timeout, key);//validateEmailFull

		result = resp.getValidateEmailInfo();

		error = resp.getError();
		if(resp == null || (error != null && error.getTypeCode() == "3"))
		{
			throw new Exception();
		}
		
		}
		catch(Exception e)
		{	//FAILOVER- USE BACKUP NOW
			try{
				//CALL SOAP USING BACKUP URL (Change the endpoint)
				resp = soap.validateEmailAddress(email, allowcorrections, timeout, key);

				result = resp.getValidateEmailInfo();

				error = resp.getError();

			}
			catch(Exception ex)
			{
		
				throw new Exception("Both Primary and Backup soap calls failed: " + ex.getMessage());
			}
		}


Email Validation 3 PHP Code Snippets
// Set these values per web service <as needed>
$wsdlUrl = "https://trial.serviceobjects.com/ev3/soap.svc?wsdl";
$backupWsdlUrl = "https://trial.serviceobjects.com/ev3/soap.svc?wsdl";

// Create the SoapClient and pass the URL to the WSDL file and optional parameters as needed
// $soapClient = new SoapClient($wsdlUrl, array("trace" => true, "exceptions" => false,));


$Email = trim($Email);
$AllowCorrections=trim($AllowCorrections);
$Timeout=trim($Timeout);
$LicenseKey = trim($LicenseKey);

$params['EmailAddress'] = $Email;
$params['AllowCorrections']=$AllowCorrections;
$params['Timeout']=$Timeout;
$params['LicenseKey'] = $LicenseKey;


// variable cleanup before generating url

$Email = strtr($Email,' ','+');
$AllowCorrections = strtr($AllowCorrections,' ','+');
$Timeout = strtr($Timeout,' ','+');


echo "<hr><h4>Email Validation 3 Result</h4><br><a href='https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=".$Email."&AllowCorrections=".$AllowCorrections."&Timeout=".$Timeout."&LicenseKey=".$LicenseKey."'>Raw XML output</a><br>";
try{
$soapClient = new SoapClient($wsdlUrl, array( "trace" => 1 ));
$result = $soapClient->ValidateEmailAddress($params);
}
catch(Exception $e)
	{
		try
		{
		$soapClient = new SoapClient($backupWsdlUrl, array( "trace" => 1 ));
		$result = $soapClient->ValidateEmailAddress($params); 
		}
		catch(Exception $ex)
		{//Both soap calls failed
			echo "<b> Primary and backup wsdls failed </b>";
			echo "$ex";
		}
	
	}


Email Validation 3 RoR Code Snippets
#Formats inputs into a hash to pass to Soap Client
		message = 	{
					"EmailAddress" => @request.email,
					"AllowCorrections" => @request.allowcorrections,
					"Timeout" => @request.timeout,
					"LicenseKey" => @request.licensekey,
					}

		#Implemented to make the code more readable when accessing the hash			
		@ev3response = :validate_email_address_response
		@ev3result = :validate_email_address_result
		@ev3info = :validate_email_info
		@ev3error = :error

		#Set Primary and Backup URLs here as needed
		dotsEV3Primary = "https://trial.serviceobjects.com/ev3/soap.svc?wsdl"
		dotsEV3Backup = "https://trial.serviceobjects.com/ev3/soap.svc?wsdl"

		begin
			#initializes the soap client. The convert request keys global is necessary to receive a response from the service.
			client = Savon.client(	wsdl: dotsEV3Primary )
			#Calls the validate_email_address operation with given inptus and converts response to a hash.
			response = client.call(:validate_email_address, message: message).to_hash

			#Checks to see what results came back from the service
			processresults(response)			
			
		#If an error occurs during the call, this will use the dotsEV3Backup url and attempt to retrieve data.
		rescue Savon::Error => e
			begin
			backupclient = Savon.client(wsdl: dotsEV3Backup)

			#Sets the response to the backclient call to the ValidateEmailAddress operation and converts response to a hash.
			response = backupclient.call(:validate_email_address, message: message).to_hash
			processresults(response)

			#If dotsEV3Backup failed, this will display the error received from the server
			rescue Savon::Error =>error
			end
		end
	end
	private 
	def processresults(response)	
			#Processes Error Response from soap Client		
			#Processes Valid response from soap client	
			end
	end


Email Validation 3 Python Code Snippets
mEmailAddress =  EmailAddress.get()
if mEmailAddress is None or  mEmailAddress == "":
     mEmailAddress = " "
mAllowCorrections =  AllowCorrections.get()
if mAllowCorrections is None or  mAllowCorrections == "":
     mAllowCorrections = " "
mTimeout =  Timeout.get()
if mTimeout is None or  mTimeout == "":
     mTimeout = " "
mLicenseKey = LicenseKey.get()
if mLicenseKey is None or mLicenseKey == "":
    mLicenseKey = " "
#Set the primary and backup URLs as needed
primaryURL = 'https://trial.serviceobjects.com/ev3/soap.svc?wsdl'
backupURL = 'https://trial.serviceobjects.com/ev3/soap.svc?wsdl'
#This block of code calls the web service and prints the resulting values to the screen
try:
    client = Client(primaryURL)
    result = client.service.ValidateEmailAddress(EmailAddress= mEmailAddress, AllowCorrections=mAllowCorrections, Timeout=mTimeout, LicenseKey=mLicenseKey)


Email Validation 3 ColdFusion Snippet
<!--Makes Request to web service --->
<cfscript>
		try
		{
			if (isDefined("form.Action") AND Action neq "")
			{
				wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/ev3/soap.svc?wsdl");							  
				outputs = wsresponse.validateEmailAddress("#EmailAddress#", "#AllowCorrections#", "#Timeout#", "#LicenseKey#");
			}
		}
	catch(any Exception){
		try
			{
				if (isDefined("form.Action") AND Action neq "")
				{
					wsresponse = CreateObject("webservice", "https://trial.serviceobjects.com/ev3/soap.svc?wsdl");							  
					outputs = wsresponse.validateEmailAddress("#EmailAddress#", "#AllowCorrections#", "#Timeout#", "#LicenseKey#");
				}
			}
			catch(any Exception)	{
		  		 writeoutput("An Error Has Occured. Please Reload and try again");		  		 
		 		}
	    }
</cfscript>


Email Validation 3 VB Snippet
Dim ws As New EV3.EV3LibraryClient
Dim response As EV3.ValidateEmailResponse

response = ws.ValidateEmailAddress(EmailAddress.Text, AllowCorrections.Text, Timeout.Text, LicenseKey.Text)
If (response.Error Is Nothing) Then
    ProcessValidResponse(response)
Else
    ProcessErrorResponse(response.Error)
End If


Email Validation 3 Apex Code Snippet
wwwServiceobjectsComEV3.ValidateEmailResponse result;
try{
wwwServiceobjectsComEV3.DOTSEmailValidation3 client = new wwwServiceobjectsComEV3.DOTSEmailValidation3();
result = client.ValidateEmailAddress([EmailAddress], [AllowCorrections], [Timeout], [Licensekey]);
}
catch(Exception ex){
 //If the first request failed try the failover endpoint
wwwServiceobjectsComEV3.DOTSEmailValidation3 backupClient = new wwwServiceobjectsComEV3.DOTSEmailValidation3();
//The backup environment will be provided to you upon purchasing a production license key
backupClient.endpoint_x = 'https://trial.serviceobjects.com/EV3/soap.svc/soap';
result = backupClient.ValidateEmailAddress([EmailAddress], [AllowCorrections], [Timeout], [Licensekey]);
}


Email Validation 3 TSQL Code Snippet
SET @requestBody ='<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">'+
				   '<s:Body>'+
				   '<ValidateEmailAddress xmlns="http://www.serviceobjects.com">'+
				   '<EmailAddress>' + @email + '</EmailAddress>'+
				   '<AllowCorrections>' + @allowcorrections + '</AllowCorrections>'+
				   '<Timeout>' + @timeout + '</Timeout>'+
				   '<LicenseKey>' + @key + '</LicenseKey>'+
				   '</ValidateEmailAddress>'+
				   '</s:Body>'+
				   '</s:Envelope>'
SET @requestLength = LEN(@requestBody)
	--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://ws.serviceobjects.com/ev3/soap.svc/soap', false
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'ws.serviceobjects.com'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"https://www.serviceobjects.com/IEV3Library/ValidateEmailAddress"'
	EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
	EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
	EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
	EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'POST', 'https://wsbackup.serviceobjects.com/ev3/soap.svc/soap', false
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'HOST', 'wsbackup.serviceobjects.com'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Type', 'text/xml; charset=UTF-8'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'SOAPAction', '"https://www.serviceobjects.com/IEV3Library/ValidateEmailAddress"'
		EXEC sp_OAMethod @obj, 'setRequestHeader', NULL, 'Content-Length', @requestLength 
		EXEC sp_OAMethod @obj, 'send', NULL, @requestBody
		EXEC sp_OAGetProperty @obj, 'Status', @responseCode OUTPUT
		EXEC sp_OAGetProperty @obj, 'StatusText', @statusText OUTPUT
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUTPUT
	END
END



Email Validation 3 C# Rest Code Snippet
EV3Response result = null;
string mainURL = "https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailInfo?" + "EmailAddress=" + email + "&AllowCorrections=" + allowcorrections + "&Timeout=" + timeout + "&LicenseKey=" + licenseKey;
string backupURL = "https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailInfo?" + "EmailAddress=" + email + "&AllowCorrections=" + allowcorrections + "&Timeout=" + timeout + "&LicenseKey=" + licenseKey;
try
{
	HttpWebRequest request = WebRequest.Create(mainURL) as HttpWebRequest;
	request.Timeout = 5000;//timeout for get operation
	using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
	{
	    if (response.StatusCode != HttpStatusCode.OK)
		{
	        throw new Exception(String.Format("Server error (HTTP {0}: {1}).",response.StatusCode,response.StatusDescription));
		}
	    //parse response
	    DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(EV3Response));
	    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
	    result = objResponse as EV3Response;
	}
}
catch (Exception e)
{   //ERROR IN MAIN URL - USING BACKUP
	HttpWebRequest request = WebRequest.Create(backupURL) as HttpWebRequest;
	request.Timeout = 5000;//timeout for get operation
	using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
	{
	    if (response.StatusCode != HttpStatusCode.OK)
		{
	        throw new Exception(String.Format("Server error (HTTP {0}: {1}).",response.StatusCode,response.StatusDescription));
		}
	    //parse response
	    DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(EV3Response));
	    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
	    result = objResponse as EV3Response;
	}
}


Email Validation 3 Java Rest Code Snippet
ValidateEmailResponse.Error error = null;
ValidateEmailResponse.ValidateEmailInfo info = null;
try {

	String email = request.getParameter("iEmail");
	String allowcorrections = request.getParameter("iAllowCorrections");
	String timeout = request.getParameter("iTimeout");
	String licenseKey = request.getParameter("iKey");

	EV3RestClient EV3Client = new EV3RestClient();
	ValidateEmailResponse result = EV3Client.ValidateEmailResponse(email, allowcorrections, timeout, licenseKey);
	if (result != null) {
		error = result.error;
		info = result.ValidateEmailInfo;
	}



Email Validation 3 PHP Rest Code Snippets
// variable cleanup before generating url
$Email = trim($Email);
$AllowCorrections = trim($AllowCorrections);
$Timeout = trim($Timeout);
$LicenseKey = trim($LicenseKey);


$URL = "https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailInfo?EmailAddress=".urlencode($Email)."&AllowCorrections=".urlencode($AllowCorrections)."&Timeout=".urlencode($Timeout)."&LicenseKey=".urlencode($LicenseKey);

//use backup url once given purchased license key
$backupURL = "https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailInfo?EmailAddress=".urlencode($Email)."&AllowCorrections=".urlencode($AllowCorrections)."&Timeout=".urlencode($Timeout)."&LicenseKey=".urlencode($LicenseKey);


	// Get cURL resource
	$curl = curl_init();
	curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $URL, CURLOPT_USERAGENT => 'Service Objects Email Validation 3'));
	curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
	// Send the request & save response to $resp
	$resp = curl_exec($curl);
	
	// Close request to clear up some resources
	if($resp == false)
	{
		echo "IN back up block";
		curl_setopt_array($curl, array(CURLOPT_RETURNTRANSFER => 1, CURLOPT_URL => $backupURL, CURLOPT_USERAGENT => 'Service Objects Email Validation 3'));
		curl_setopt($curl, CURLOPT_TIMEOUT, 50); //timeout in seconds
		// Send the request & save response to $resp
		$resp = curl_exec($curl);
		if($resp == false)
		{
			echo "<b> Both rest calls failed </b>";
			curl_close($curl);
			return;
		}
	
	
	}
curl_close($curl);


Email Validation 3 RoR Rest Code Snippets
  #This sets the default timeout for HTTParty get operation. This must be set in order to use the gem
      default_timeout = 10

      licensekey = @request.licensekey
      timeout = @request.timeout
      allowcorrections = @request.allowcorrections
      email = @request.email
      #Checks the users input and sets values equal to an underscore if the user entered nil.
      #These can be changed to whatever your application might need.
      email = "" if @request.email == nil
      timeout = "" if @request.timeout == nil
      allowcorrections = "" if @request.allowcorrections == nil
      licensekey = "" if @request.licensekey == nil

     #Set Primary and Backup URLs as needed
      primaryURL = URI.encode("https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailAddress?EmailAddress=" + email + "&AllowCorrections=" + allowcorrections + "&Timeout=" + timeout + "&LicenseKey=" + licensekey )
      backupURL = URI.encode("https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailAddress?EmailAddress=" + email + "&AllowCorrections=" + allowcorrections + "&Timeout=" + timeout + "&LicenseKey=" + licensekey )
     
	 #These are set to access the hash that is returned
      @validateemailresponse = "ValidateEmailResponse"
      @validateemailinfo = "ValidateEmailInfo"
      @error = "Error"

      #Begins the call the RESTful web service
      begin
        response = HTTParty.get(primaryURL, timeout: default_timeout)
        #processes the response to display to the screen
        
        #Passes the response from HTTParty and the hash key values to this method
        processresults(response)
       rescue StandardError => e
       		begin
       		#uses the backupURl in the event that the service encountered an error
       		response = HTTParty.get(backupURL, timeout: default_timeout)
          
          #processes the response returned from using the backupURL
           processresults(response)

          #If the backup url railed this will raise an error and display the 
          #error message returned from the HTTParty gem.
       		rescue StandardError => error
       		end
      end
  end
	private 
      def processresults(response)  
      #Processes Error Response from rest Client    
      #Processes Valid response from rest client  
     end


Email Validation 3 PythonCode Snippets
mEmailAddress =  EmailAddress.get()
if mEmailAddress is None or  mEmailAddress == "":
     mEmailAddress = " "
mAllowCorrections =  AllowCorrections.get()
if mAllowCorrections is None or  mAllowCorrections == "":
     mAllowCorrections = " "
mTimeout =  Timeout.get()
if mTimeout is None or  mTimeout == "":
     mTimeout = " "
mLicenseKey = LicenseKey.get()
if mLicenseKey is None or mLicenseKey == "":
    mLicenseKey = " "
#Set the primary and backup URL as needed.
primaryURL = 'https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?'
backupURL = 'https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?'
#The Requests package allows the user to format the path parameters like so instead of having to manually insert them into the URL
inputs = {'EmailAddress': mEmailAddress, 'AllowCorrections': mAllowCorrections, 'Timeout': mTimeout, 'LicenseKey': mLicenseKey}
try:
    result = requests.get(primaryURL, params=inputs)
    #Parses the XML response from the service into a python dictionary type
    outputs = xmltodict.parse(result.content)
    #checks the output for Errors and displays the info accordingly
    if 'Error' in outputs['ValidateEmailResponse']:
        #loops through the response from the service and prints the values to the screen.
        for key, value in outputs['ValidateEmailResponse']['Error'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()
    else:
        for key, value in outputs['ValidateEmailResponse']['ValidateEmailInfo'].iteritems():
            Label(swin.window, text=str(key) + " : " + str(value)).pack()


Email Validation 3 ColdFusion Code Snippet
<!--Makes Request to web service --->
<cfIf isDefined("form.Action") AND Action neq ""  >
	<cftry>
		<cfset primaryURL = "https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=#EmailAddress#&AllowCorrections=#AllowCorrections#&Timeout=#Timeout#&LicenseKey=#LicenseKey#">
		<cfhttp url="#primaryURL#" method="get" result="response">
		<cfset outputs = XmlParse(response.FileContent)>
	<cfcatch >
		<cftry>
			<cfset backupURL = "https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=#EmailAddress#&AllowCorrections=#AllowCorrections#&Timeout=#Timeout#&LicenseKey=#LicenseKey#">
			<cfhttp url="#backupURL#" method="get" result="response">
			<cfset outputs = XmlParse(outputs.FileContent)>				
			<cfcatch >
				<cfoutput >
					The Following Error Occured: #response.StatusCode#
				</cfoutput>
			</cfcatch>
		</cftry>
	</cfcatch>
	</cftry>
</cfif>


Email Validation 3 VB Rest Snippet
email = Me.EmailAddress.Text
licensekey = Me.LicenseKey.Text
allowcorrections = Me.AllowCorrections.Text
timeout = Me.Timeout.Text
Try
    'encodes the URLs for the get Call. Set the primary and back urls as necessary
    Dim primaryurl As String = "https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=" & email + "&AllowCorrections=" + allowcorrections + "&Timeout=" + timeout + "&LicenseKey=" & licensekey
    Dim backupurl As String = "https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=" & email + "&AllowCorrections=" + allowcorrections + "&Timeout=" + timeout + "&LicenseKey=" & licensekey
    Dim wsresponse As EV3Response.ValidateEmailResponse = httpGet(primaryurl)

    'checks if a response was returned from the service, uses the backup url if response is null or a fatal error occured.
    If wsresponse Is Nothing OrElse (wsresponse.[Error] IsNot Nothing AndAlso wsresponse.[Error].TypeCode = "3") Then
        wsresponse = httpGet(backupurl)
    End If
    If wsresponse.[Error] IsNot Nothing Then
        ProcessErrorResponse(wsresponse.[Error])
    Else
        ProcessSuccessfulResponse(wsresponse)
    End If
Catch ex As Exception
    'Displays the relevant error mesasge if both backup and primary urls failed.
    resultsLabel.Text = ex.Message
    resultsLabel.Visible = True
End Try


Email Validation 3 TSQL Rest Code Snippet
--If a production key is purchased, this will execute the failover 
IF @isLiveKey = 1
BEGIN
	SET @sUrl = 'https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=' + @email + '&AllowCorrections=' + @allowcorrections + '&Timeout=' + @timeout + '&LicenseKey=' + @key
	EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
	EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sUrl, false
	EXEC sp_OAMethod @obj, 'send'
	EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
			
	--Checks the Response for a fatal error or if null. 
	IF @response IS NULL
	BEGIN
		SET @sBackupUrl = 'https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailAddress?EmailAddress=' + @email + '&AllowCorrections=' + @allowcorrections + '&Timeout=' + @timeout + '&LicenseKey=' + @key
		EXEC sp_OACreate 'MSXML2.ServerXMLHttp', @obj OUT
		EXEC sp_OAMethod @obj, 'Open', NULL, 'Get', @sBackupUrl, false
		EXEC sp_OAMethod @obj, 'send'
		EXEC sp_OAGetProperty @obj, 'responseText', @response OUT
	END
END

You can find and download full sample code to our services in various languages (PHP, JAVA and C#) by clicking here. Below is a C# version.

If you are looking for a particular integration not listed in our documentation please contact us at support@serviceobjects.com.

C#
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Configuration;
using System.Data;
using System.Net;
using System.Runtime.Serialization.Json;
namespace EV3_rest
{
    public partial class _Default : System.Web.UI.Page
    {
        static string WEB_SERVICE_PRIMARY_URL; //Included in email from Service Objects
        static string WEB_SERVICE_BACKUP_URL; //Included in email from Service Objects (LIVE customers only)
        static int WEB_SERVICE_REQUEST_TIMEOUT; //In milliseconds
        protected void Page_Load(object sender, EventArgs e)
        {
            try
            {
                ErrorLabel.Visible = false;
                ErrorGrid.Visible = false;
                ResultGrid.Visible = false;
                WEB_SERVICE_REQUEST_TIMEOUT = Convert.ToInt32(ConfigurationManager.AppSettings["WebServiceRequestTimeout"]);
                WEB_SERVICE_PRIMARY_URL = ConfigurationManager.AppSettings["EV3_PRIMARY.EV3"];
                if (string.IsNullOrWhiteSpace(WEB_SERVICE_PRIMARY_URL))
                    throw new System.Exception("Primary URL not set. Check your Web.config file.");
                WEB_SERVICE_BACKUP_URL = ConfigurationManager.AppSettings["EV3_BACKUP.EV3"];
                if (string.IsNullOrWhiteSpace(WEB_SERVICE_BACKUP_URL))
                    throw new System.Exception("Backup URL not set. Check your Web.config file.");
            }
            catch (Exception ex)
            {
                ErrorLabel.Visible = true;
                ErrorLabel.Text = "Page load Error: "+ ex.Message;
            }
        }
        protected void btn_GO_Click(object sender, EventArgs e)
        {
            string email, licenseKey;
            email = inputEmailAddress.Text; licenseKey = inputLicenseKey.Text;
            try
            {
                //NOTE: A missing parameter is not allowed
                if (email == "")
                    email = " ";
                if (String.IsNullOrWhiteSpace(licenseKey))
                    licenseKey = "yourDevKey";
                
                EV3Response response = MakeRequest(email, licenseKey);
                ProcessResponse(response);
            }
            catch (Exception ex)
            {
                ErrorLabel.Text = ex.Message;
                ErrorLabel.Visible = true;
            }
        }
        //Creates URL and requests response from service 
        private static EV3Response MakeRequest(string email, string licenseKey)
        {
         
         /* 
         * Due to RFC compliance, the use of URL Paths has character limitations.  
         * Certain characters are invalid and cause HTTP Errors; these characters  
         * include #, /, ?,\ as well as some high bit characters.  
         * 
         * If you suspect that this may be an issue for you then it is recommended to change your 
         * request from the URL path parameter format to the query string parameter format.  
         * Example:  
         *     FROM {data}/{data2}/{key}?format=json  
         *     TO parameter1={data1}&parameter2={data2}&licensekey={key} 
         * Another alternative is to use HTTP Post instead of HTTP Get. 
         */
            
            EV3Response result = null;
            string mainURL = WEB_SERVICE_PRIMARY_URL + email + "/" + licenseKey + "?format=json";
            string backupURL = WEB_SERVICE_BACKUP_URL + email + "/" + licenseKey + "?format=json";
            try
            {
                result = HttpGet(mainURL);
                //NULL ERROR || FATAL ERROR RETURNED -- TRY BACKUP 
                if (result == null || (result.error != null && result.error.TypeCode == "3"))
                {
                    return HttpGet(backupURL);
                }
                else
                {
                    return result;
                }
            }
            catch (Exception e)
            {   //ERROR IN MAIN URL - USING BACKUP
                return HttpGet(backupURL);
            }
        }
        //HTTP Get Method and parse into user-defined object
        private static EV3Response HttpGet(string requestUrl)
        {
            try
            {
                //NOTE: URL encoding occurs automatically when creating the web request
                HttpWebRequest request = WebRequest.Create(requestUrl) as HttpWebRequest;
                request.Timeout = WEB_SERVICE_REQUEST_TIMEOUT;//timeout for get operation
                using (HttpWebResponse response = request.GetResponse() as HttpWebResponse)
                {
                    if (response.StatusCode != HttpStatusCode.OK)
                        throw new Exception(String.Format(
                        "Server error (HTTP {0}: {1}).",
                        response.StatusCode,
                        response.StatusDescription));
                    //parse response
                    DataContractJsonSerializer jsonSerializer = new DataContractJsonSerializer(typeof(EV3Response));
                    object objResponse = jsonSerializer.ReadObject(response.GetResponseStream());
                    EV3Response jsonResponse = objResponse as EV3Response;
                    return jsonResponse;
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process the returned user-defined object
        private void ProcessResponse(EV3Response response)
        {
            try
            {
                //processing result
                if (response.error == null)
                {
                    ProcessResult(response.EmailInfo);
                }
                //processing error
                else
                {
                    ProcessError(response.error);
                }
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the result values
        private void ProcessResult(ValidateEmailInfo result)
        {
            try
            {
                DataTable dtProvider = new DataTable();
                dtProvider.Columns.Add(new DataColumn("Output", typeof(string)));
                dtProvider.Columns.Add(new DataColumn("Values", typeof(string)));
                dtProvider.Rows.Add("Score", result.Score);
                dtProvider.Rows.Add("IsDeliverable", result.IsDeliverable);
                .
				.
				.
                dtProvider.Rows.Add("NotesDescriptions", result.NotesDescriptions);
                ResultGrid.Visible = true;
                ErrorGrid.Visible = false;
                ResultGrid.DataSource = new DataView(dtProvider);
                ResultGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
        //Process and display the error values
        private void ProcessError(Error error)
        {
            try
            {
                DataTable dtError = new DataTable();
                //A case statement is used here because it is often useful to do different
                //things depeneding on which general type of error occurs.
                //Handle the errors according to your production needs.
                switch (System.Convert.ToInt32(error.TypeCode))
                {
                    case 1:
                        //Authorization Error
                        break;
                    case 2:
                        //User Input Error
                        break;
                    case 4:
                        //Domain Specific Error
                        break;
                    default:
                        //default (error code 3) Service Objects Fatal Error Error
                        break;
                }
                dtError.Columns.Add(new DataColumn("Output", typeof(string)));
                dtError.Columns.Add(new DataColumn("Values", typeof(string)));
                dtError.Rows.Add("Type", error.Type);
                .
				.
				.
                dtError.Rows.Add("DescCode", error.DescCode);
                //
                ResultGrid.Visible = false;
                ErrorGrid.Visible = true;
                ErrorGrid.DataSource = new DataView(dtError);
                ErrorGrid.DataBind();
            }
            catch (Exception e)
            {
                throw e;
            }
        }
    }
}


ValidateEmailAddress Example Request and Response


URL Request: 
https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailInfo?EmailAddress=support@serviceobjects.com&AllowCorrections=true&Timeout=500&LicenseKey=yourDevKey


Json Response
{"ValidateEmailInfo":{"Score":0,"IsDeliverable":"true","EmailAddressIn":"support@serviceobjects.com","EmailAddressOut":"support@serviceobjects.com","EmailCorrected":false,"Box":"support","Domain":"serviceobjects.com","TopLevelDomain":".com","TopLevelDomainDescription":"commercial","IsSMTPServerGood":"true","IsCatchAllDomain":"false","IsSMTPMailBoxGood":"true","WarningCodes":"","WarningDescriptions":"","NotesCodes":"3,4","NotesDescriptions":"Role,BusinessAddress"}}


XML Request: 
https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailInfo?EmailAddress=support@serviceobjects.com&AllowCorrections=true&Timeout=500&LicenseKey=yourDevKey


XML Response
<ValidateEmailResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ValidateEmailInfo>
<Score>0</Score>
<IsDeliverable>true</IsDeliverable>
<EmailAddressIn>support@serviceobjects.com</EmailAddressIn>
<EmailAddressOut>support@serviceobjects.com</EmailAddressOut>
<EmailCorrected>false</EmailCorrected>
<Box>support</Box>
<Domain>serviceobjects.com</Domain>
<TopLevelDomain>.com</TopLevelDomain>
<TopLevelDomainDescription>commercial</TopLevelDomainDescription>
<IsSMTPServerGood>true</IsSMTPServerGood>
<IsCatchAllDomain>false</IsCatchAllDomain>
<IsSMTPMailBoxGood>true</IsSMTPMailBoxGood>
<WarningCodes/>
<WarningDescriptions/>
<NotesCodes>3,4</NotesCodes>
<NotesDescriptions>Role,BusinessAddress</NotesDescriptions>

</ValidateEmailInfo>
</ValidateEmailResponse>

ValidateEmailFull Example Request and Response


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/support@serviceobjects.com/yourDevKey?format=json


Json Response
{"ValidateEmailInfo":{"Score":0,"IsDeliverable":"true","EmailAddressIn":"support@serviceobjects.com","EmailAddressOut":"support@serviceobjects.com","EmailCorrected":false,"Box":"support","Domain":"serviceobjects.com","TopLevelDomain":".com","TopLevelDomainDescription":"commercial","IsSMTPServerGood":"true","IsCatchAllDomain":"false","IsSMTPMailBoxGood":"true","WarningCodes":"","WarningDescriptions":"","NotesCodes":"3,4","NotesDescriptions":"Role,BusinessAddress"}}


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/support@serviceobjects.com/yourDevKey?format=xml


XML Response
<ValidateEmailResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ValidateEmailInfo>
<Score>0</Score>
<IsDeliverable>true</IsDeliverable>
<EmailAddressIn>support@serviceobjects.com</EmailAddressIn>
<EmailAddressOut>support@serviceobjects.com</EmailAddressOut>
<EmailCorrected>false</EmailCorrected>
<Box>support</Box>
<Domain>serviceobjects.com</Domain>
<TopLevelDomain>.com</TopLevelDomain>
<TopLevelDomainDescription>commercial</TopLevelDomainDescription>
<IsSMTPServerGood>true</IsSMTPServerGood>
<IsCatchAllDomain>false</IsCatchAllDomain>
<IsSMTPMailBoxGood>true</IsSMTPMailBoxGood>
<WarningCodes/>
<WarningDescriptions/>
<NotesCodes>3,4</NotesCodes>
<NotesDescriptions>Role,BusinessAddress</NotesDescriptions>

</ValidateEmailInfo>
</ValidateEmailResponse>

ValidateEmailFast Example Request and Response


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/support@serviceobjects.com/yourDevKey?format=json


Json Response
{"ValidateEmailInfo":{"Score":0,"IsDeliverable":"true","EmailAddressIn":"support@serviceobjects.com","EmailAddressOut":"support@serviceobjects.com","EmailCorrected":false,"Box":"support","Domain":"serviceobjects.com","TopLevelDomain":".com","TopLevelDomainDescription":"commercial","IsSMTPServerGood":"true","IsCatchAllDomain":"false","IsSMTPMailBoxGood":"true","WarningCodes":"","WarningDescriptions":"","NotesCodes":"3,4","NotesDescriptions":"Role,BusinessAddress"}}


XML Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/support@serviceobjects.com/yourDevKey?format=xml


XML Response
<ValidateEmailResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ValidateEmailInfo>
<Score>0</Score>
<IsDeliverable>true</IsDeliverable>
<EmailAddressIn>support@serviceobjects.com</EmailAddressIn>
<EmailAddressOut>support@serviceobjects.com</EmailAddressOut>
<EmailCorrected>false</EmailCorrected>
<Box>support</Box>
<Domain>serviceobjects.com</Domain>
<TopLevelDomain>.com</TopLevelDomain>
<TopLevelDomainDescription>commercial</TopLevelDomainDescription>
<IsSMTPServerGood>true</IsSMTPServerGood>
<IsCatchAllDomain>false</IsCatchAllDomain>
<IsSMTPMailBoxGood>true</IsSMTPMailBoxGood>
<WarningCodes/>
<WarningDescriptions/>
<NotesCodes>3,4</NotesCodes>
<NotesDescriptions>Role,BusinessAddress</NotesDescriptions>

</ValidateEmailInfo>
</ValidateEmailResponse>

ValidateEmailFullNoCorrections Example Request and Response


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/NoCorrections/support@serviceobjects.com/yourDevKey?format=json


Json Response
{"ValidateEmailInfo":{"Score":0,"IsDeliverable":"true","EmailAddressIn":"support@serviceobjects.com","EmailAddressOut":"support@serviceobjects.com","EmailCorrected":false,"Box":"support","Domain":"serviceobjects.com","TopLevelDomain":".com","TopLevelDomainDescription":"commercial","IsSMTPServerGood":"true","IsCatchAllDomain":"false","IsSMTPMailBoxGood":"true","WarningCodes":"","WarningDescriptions":"","NotesCodes":"3,4","NotesDescriptions":"Role,BusinessAddress"}}


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/NoCorrections/support@serviceobjects.com/yourDevKey?format=xml


XML Response
<ValidateEmailResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ValidateEmailInfo>
<Score>0</Score>
<IsDeliverable>true</IsDeliverable>
<EmailAddressIn>support@serviceobjects.com</EmailAddressIn>
<EmailAddressOut>support@serviceobjects.com</EmailAddressOut>
<EmailCorrected>false</EmailCorrected>
<Box>support</Box>
<Domain>serviceobjects.com</Domain>
<TopLevelDomain>.com</TopLevelDomain>
<TopLevelDomainDescription>commercial</TopLevelDomainDescription>
<IsSMTPServerGood>true</IsSMTPServerGood>
<IsCatchAllDomain>false</IsCatchAllDomain>
<IsSMTPMailBoxGood>true</IsSMTPMailBoxGood>
<WarningCodes/>
<WarningDescriptions/>
<NotesCodes>3,4</NotesCodes>
<NotesDescriptions>Role,BusinessAddress</NotesDescriptions>

</ValidateEmailInfo>
</ValidateEmailResponse>

ValidateEmailFastNoCorrections Example Request and Response


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/NoCorrections/support@serviceobjects.com/yourDevKey?format=json


Json Response
{"ValidateEmailInfo":{"Score":0,"IsDeliverable":"true","EmailAddressIn":"support@serviceobjects.com","EmailAddressOut":"support@serviceobjects.com","EmailCorrected":false,"Box":"support","Domain":"serviceobjects.com","TopLevelDomain":".com","TopLevelDomainDescription":"commercial","IsSMTPServerGood":"true","IsCatchAllDomain":"false","IsSMTPMailBoxGood":"true","WarningCodes":"","WarningDescriptions":"","NotesCodes":"3,4","NotesDescriptions":"Role,BusinessAddress"}}


URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/NoCorrections/support@serviceobjects.com/yourDevKey?format=xml


XML Response
<ValidateEmailResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<ValidateEmailInfo>
<Score>0</Score>
<IsDeliverable>true</IsDeliverable>
<EmailAddressIn>support@serviceobjects.com</EmailAddressIn>
<EmailAddressOut>support@serviceobjects.com</EmailAddressOut>
<EmailCorrected>false</EmailCorrected>
<Box>support</Box>
<Domain>serviceobjects.com</Domain>
<TopLevelDomain>.com</TopLevelDomain>
<TopLevelDomainDescription>commercial</TopLevelDomainDescription>
<IsSMTPServerGood>true</IsSMTPServerGood>
<IsCatchAllDomain>false</IsCatchAllDomain>
<IsSMTPMailBoxGood>true</IsSMTPMailBoxGood>
<WarningCodes/>
<WarningDescriptions/>
<NotesCodes>3,4</NotesCodes>
<NotesDescriptions>Role,BusinessAddress</NotesDescriptions>

</ValidateEmailInfo>
</ValidateEmailResponse>



List of Operations

ValidateEmailAddress (Recommended operation)
Validates and verifies an email address via a full suite of tests and real-time SMTP checks. This operation performs real-time server-to-server verification via SMTP communication. This operation allows the user to specify a timeout value, in milliseconds, for how long it can take to perform SMTP level checks. A minimum of 200 milliseconds is required to perform these checks. However, results are dependent on the network speed of an email's host, which may require several seconds to verify. Average mail server response times are approximately between 2-3 seconds, but some slower mail servers may take 15 seconds or more to verify. 

URL Format Examples:

JSON: https://trial.serviceobjects.com/ev3/web.svc/json/ValidateEmailInfo?Email={EMAILADDRESS}&AllowCorrections={ALLOWCORRECTIONS}&Timeout={TIMEOUT}&LicenseKey={LICENSEKEY}

XML: https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailInfo?Email={EMAILADDRESS}&AllowCorrections={ALLOWCORRECTIONS}&Timeout={TIMEOUT}&LicenseKey={LICENSEKEY}

ValidateEmailFull
Corrects, validates and verifies an email address via a full suite of tests and real-time SMTP checks. Since this operation performs real-time verification via SMTP communication the response time is dependent on the network speed of an email's host and may take several seconds. The average response time for this operation is approximately 2 seconds, but the operation can take as long as 10 seconds.

URL Format Examples:

JSON: https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/{EMAILADDRESS}/{LICENSEKEY}?format=json

XML: https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/{EMAILADDRESS}/{LICENSEKEY}?format=xml

ValidateEmailFast
This operation has the same inputs and outputs as ValidateEmailFull. This check will not perform any real-time SMTP level checks, however it may still provide SMTP level information via one of our other mechanisms.

URL Format Examples:

JSON: https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/{EMAILADDRESS}/{LICENSEKEY}?format=json

XML: https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/{EMAILADDRESS}/{LICENSEKEY}?format=xml

ValidateEmailFullNoCorrections
The same as ValidateEmailFull but the service will not attempt to correct the email address.


ValidateEmailFastNoCorrections
The same as ValidateEmailFast but the service will not attempt to correct the email address.

Operation Definitions

This section defines the input, output and behavior of the web services in EV3.

Important Note!
SMTP level data may be unknown due to a real-time timeout or company policy to limit SMTP requests to a domain. Our system is optimized to get around this limitation, but if you do receive some unknown flags then try the email again a few hours later. There is a very good chance we will have acquired the information.

ValidateEmailAddress (Recommended Operation)

 Input Values

Name

Type

Description

EmailAddress

String

The email address you wish to validate.

AllowCorrectionsStringAccepts true or false. The service will attempt to correct an email address if set to true. Otherwise the email address will be left unaltered if set to false.
TimeoutStringThis value specifies how long the service is allowed to wait for all real-time network level checks to finish. Real-time checks consist primarily of DNS and SMTP level verification. Timeout time is in milliseconds. A minimum value of 200ms is required.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/email/email-verification-service

*All input values are required
 

ValidateEmailFull & ValidateEmailFast

 Input Values

Name

Type

Description

EmailAddress

String

The email address you wish to validate.

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

Outputs Values

Name

Type

Values

Description

ScoreInteger0
1
2
3
4
An estimate on the validity of the email address.[1] 
0 = Email is Good
1 = Email is Probably Good
2 = Unknown
3 = Email is Probably Bad
4 = Email is Bad
IsDeliverableStringtrue
false
unknown
Indicates if the mail server will accept mail for the given email address.[2]

EmailAddressIn

String

Varies

Echo of input: EmailAddress

EmailAddressOutStringVariesThe cleaned and corrected email. This is the email that is validated.
EmailCorrectedBoolleanT/FIndicates if any corrections or modifications were made to the email address.

Box

String

Varies

The part to the left of the '@' symbol. Also known as the local part or the username.

Domain

String

Varies

The part to the right of the '@' symbol. The location to which the email address will be sent.

TopLevelDomain

String

Varies

The part after the rightmost '.'

TopLevelDomainDescription

String

Varies

Description of the Top Level Domain.

IsSMTPServerGood

String

true
false
unknown

Indicates if the email's mail server is operational.

IsCatchAllDomain

String

true
false
unknown

Indicates if the mail server will accept mail to any box in that domain (*@domain).

IsSMTPMailBoxGood

String

true
false
unknown

Indicates if the mail server will accept mail to the specific box.

WarningCodes

String

0-21

Indicates if one or more potential problems were found when correcting, validating and/or verifying the email address. Returns zero or more numerical warning codes in a comma-separated list.[3]

WarningDescriptions

String

Varies

Contains the warning flag(s) that corresponds to the Warning Codes. Returns zero or more warning flags in a comma-separated list.[3]

NotesCodesString0-6Displays additional notes about the email that were found during the validation process. Returns zero or more numerical note codes in a comma-separated list.[3]
NotesDescriptionStringVariesContains the note flag(s) that corresponds to the Notes Codes. Returns zero or more notes flags in a comma-separated list.[3]

[1] This value is dependent on the amount data that is available for the address. The service then analyzes the data to estimate the integrity of the address.

[2] An unknown return value indicates that either there was not enough information available about the recipient's mail server to determine deliverability or the server is a catch-all. In general, catch-all mail servers will always initially accept an email message, even if the email address does not exist.

[3] New codes and descriptions will be added as new features become available and the number of codes will increase in time. See the table below for our current list of codes & descriptions.

Warning Codes & Descriptions

The table contains a list of current and upcoming warning types that the service can report on when processing an email address.

Important Note!
New codes and descriptions will be added to the table as new features become available.


CodeWarningDescription
0UnrecognizedTLDIndicates if the top-level-domain is not recognized by ICANN.
1InvalidSyntaxIndicates if the email is syntactically invalid.
2InvalidDomainSpecificSyntaxIndicates if email is syntactically invalid for the given domain.
3InvalidDNS

Indicates if the domain is unregistered or it does not have at least one MX or A record configured to relay email.

4NoMXRecordsIndicates that the registered DNS does not have an MX record.
5Established

Indicates that the email address is known to be in bulk marketing lists.

6Alias

Indicates if the email address is believed to be an alias address.

7Bogus

Indicates if the email address is believed to be a bogus email. For example, asdf@asdf.com.

8BogusSMSAddress

Indicates if the email address is believed to be a bogus SMS domain address.

9Garbage

Indicates if the email address is believed to contain garbage-like keyboard strokes and/or garbage-like characters.

10Vulgar

Indicates if vulgar words or content are found in the email address.

11MailBoxIsFull

Indicates if the mailbox is currently full and unable to receive any new messages.

12MailboxIsBusy

Indicates if the mailbox is reported by the hosting mail server as being busy and unable to currently accept new messages.

13DisposableEmailIndicates if the email address is believed to be disposable. Disposable email address are generally only valid for a short period of time before they are disposed and are then no longer valid.
14SpamTrap

Indicates if the mailbox is believed to be a spam trap.

15KnownSpammer

Indicates if the email address is known to have participated in spam-like activities.

16BlacklistedDomain

Indicates if the domain was found to be in one or more blacklists.

17KnownComplainer

Indicates if the email address has been identified as a known complainer of receiving unsolicited mail. ** Coming Soon **

18KnownGreylisterIndicates if the mail server is known to commonly use greylisting techniques. This means that if your mail server is communicating with this domain for the first time or if you are sending bulk messages or messages in high frequency then you may be greylisted by them and experience temporary bounce backs.
19OptInRequiredIndicates if the mail server requires opting-in to send and receive messages.
20IsWhiteListOnlyIndicates if the mail server only relays messages for users that are whitelisted.
21ConnectionRefusedIndicates if the mail server refuses to accept an SMTP connection.
22Email is Bad - Subsequent checks halted.Indicates that the email address failed a critical check, such as SMTP verification.
23BotIndicates that the email address has been reported as being a known bot.

Note Codes & Descriptions

The table contains a list of current and upcoming note types that the service can report on when processing an email address.

Important Note!
New codes and descriptions will be added to the table as new features become available.


CodeNoteDescription
0CCTLDIndicates if the top-level-domain (tld) represents a specific country. For example ".us" implies United States.
1FreeIndicates if the domain of the email is a public-register domain, where users can sign up for email accounts for free.
2SMSDomain

Indicates if the domain is a known Mail-to-SMS Gateway.

3RoleIndicates if the email address appears to be a role that is designed to be anonymously managed by one or more persons.
4BusinessAddress

Indicates if the email address appears to be work related.

5GreyListedIndicates if the mail server responded with a known greylist tactic.
6MailServerTemporarilyUnavailable

Indicates that the mail server may be temporarily unavailable or too busy to respond.

7ServerConnectTimeoutIndicates that a connection to the recipient mail server could not be established.
8MailBoxTimeoutIndicates that the connection to the mail server timed out when trying to verify the email address.
9

TemporaryReject

Indicates that the email address was temporarily rejected by the mail server. This is also known as a soft-bounce and the rejection is not permanent. There are many reasons for why a mail server may respond with a temporary reject. The mailbox or server may be busy, unavailable, or using a greylist. When a mail server does this it typically wants you to wait at least 15 minutes and then try again later.

10SlowMailServerIndicates that the host mail server is known to communicate slowly and that real-time verification of an email address may not be possible unless adequate time is provided. In some cases a timeout time of 90 seconds or more may be necessary to verify email addresses with these mail servers.
11

Varies

Example: JP

***Coming Soon: Countries: The ISO2 country code for the country where the mail server(s) is located. If mail servers are found in more than one country, then all country ISO2 codes will be represented in a pipe-delimited list.
12

Varies

Example: OS|TY

***Coming Soon: Region: The region in the country where the mail server(s) is located. The region is commonly returned as a two-character abbreviation. If mail servers are found in more than one region then the value will be a pipe-delimited list of the regions.
13

Varies

Example: Osaka|Tokyo

***Coming Soon: Localities: The name of the locality where the mail sever(s) is located in. If mail servers are found in more than one locality then the value will be a pipe-delimited list of all the localities.

14

Varies

Example: 543-0062|102-0082

***Coming Soon: PostCodes: The post code of where the mail server(s) is located. If multiple post codes are found, then the value will be a pipe-delimited list.
15SMTPCheckTimeoutIndicates that SMTP communication did not finish in the allotted time. It is recommend to increase the timeout time and try again.
16TLSIndicates that the recipient mail server supports Transport Layer Security (TLS) connections for encrypted email communication.


Error

Anything that happens during a run of DOTS Email Validation 3 that causes it to be unable to finish its normal processing is an error. If an error occurs, something similar to the following will result instead of the normal/typical output: 
Example:

*Error!*

  <Type>Authorization</Type>
  <TypeCode>1</TypeCode>
  <Desc>Your license key does not work on this service.</Desc>
  <DescCode>8</DescCode>

There are four error types described below.

Error Types

Type

TypeCode

Billable

Standard Across All Gen2 Web Services

Authorization

1

No

Yes

User Input

2

Yes

No

Service Objects Fatal

3

No

Yes

Domain Specific

4

Yes

No

Error type 1: Authorization

Theses are standard to all Generation 2 DOTS Web Services.

DescCode

Desc

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available. Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service

Error type 2: User Input

User Input errors are caused when a user inputs an invalid value or fails to provide a certain input field altogether. If a developer creates a request and mistypes a parameter name, it will probably cause a User Input Error.

DescCode

Desc

1

You must input an email address in the EmailAddress field.

2

You must input a license key in the LicenseKey field.

3You must enter True or False in the AllowCorrections field.
4Invalid value for AllowCorrections. Please enter True or False.
5You must input a time out value in the timeout field.
6Invalid timeout value. Please enter a timeout value of 200 miliseconds or more.
Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning. This is standard to all Generation 2 DOTS Web Services. This is a rare error that signals either a bug in the DOTS Email Validation 3 service, or a Network/Connectivity issue.

DescCode

Desc

1

Unhandled error. Please contact Service Objects.

Error type 4: Domain Specific

Domain specific errors represent the common errors seen in Service Objects services.

DescCode

Desc

1

Operation Not Supported.

Frequently Asked Questions

How is EV3 different from EV2?

EV3 was developed with a newer framework that supports REST and JSON. The EV3 service builds on top of the core features of the EV2 service and improves overall performance, accuracy and usability. The added logic greatly improves on the service's ability to establish real-time communication with host servers to verify email addresses. Many mail servers are now configured to handle mail communication with extreme prejudice, and they employ various tactics in order to try and reduce spam and phishing bots from getting any information past them. As a result, normal SMTP verification techniques are becoming less reliable. EV3 is smart enough to not just recognize these techniques, but to also anticipate them so that they don't get in the way of the verification process.

Like EV2, the system has background processes that are constantly gathering information. If we were not able to get a piece of information on the first request, it is likely a background process will obtain it and have it ready for you next time. EV3 combines all the functionality of its predecessor and more into just two new operations. For example, email cleaning and correction is now included as part of the standard set of procedures in each operation.

I ran the same email twice with the ValidateEmailFast operation. The second request returned SMTP level information but the first time it did not. What happened?

Our system has background processes that constantly monitor new requests. We did not have the information on the first request, but the background process saw the request, and gathered the information so that it was instantly available the next time you requested it. 

I have a bunch of emails that I absolutely must have the SMTP level information for, what should I do?

You should run them first against our ValidateEmailFull operation. Then wait an hour or so and take the ones that had unknown values in the SMTP level checks and run them against our ValidateEmailFast operation. This should get nearly all of them. Continue this until all the emails have data for the SMTP level checks. The more you submit an email, the better the chances are that our background processes will be able to process it. Our system improves with use.

How fast is the service?

The ValidateEmailFast operation should typically take under one second, generally one can expect a response in about 0.3 seconds. The ValidateEmailFull operation can take anywhere from under a second to around five seconds. The average response time for the ValidateEmailFull operation is approximately 2 seconds.

My email address fails EV3's SMTP level checks, but I know it is a valid email address.

Your mail server may be down, or extremely slow. If we cannot get a response from the server there is nothing we can do but assume it is not valid. You can also send us the email address at support@serviceobjects.com and we can double check that the service is working properly.

Where do you get your information?

We get our data from a variety of public and proprietary sources. We also do real-time checks, as well as have background processes that are constantly getting new data.

I'm not technical, but I have a list of email addresses I want to validate. Can you run my list for me?

Yes! We run EV3 batches for users quite often, and would be happy to run your list once we discuss your needs. We offer a free trial batch for up to a hundred emails. Please contact sales@serviceobjects.com for details.

The sample code is giving strange errors or is crashing!

Most likely, the sample code cannot connect to Service Objects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses. The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to: https://trial.serviceobjects.com/ev3/. Then test one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn't able to connect, either. Contact your systems administrator to resolve why you are not able to connect to Service Objects.

Why are email addresses Scores for Hotmail, Yahoo, and other domains commonly marked as a one, "Probably Good", even though I know they are valid?

Email providers like Hotmail and Yahoo have catch-all domains. They will accept requests for any email address, even for addresses that do not exist. It is difficult to be certain on whether an email address with a catch-all domain is truly valid or not. This uncertainty is generally the reason why an email address will be marked as either one (Probably Good) or three (Probably Bad).

Conclusion

Service Objects is pleased to offer you a free trial of DOTS Email Validation 3.

Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS Email Validation 3, please contact sales@serviceobjects.com.


  
We want to hear from you! We're always looking to improve our developer guides. 
Please email your suggestions to devguidefeedback@serviceobjects.com.

  • No labels