DOTS Email Validation 2

Introduction

DOTS Email Validation 2 (EV2) is an XML 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 vulgarity flags.

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

Integration

Integrating EV2 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:
https://www.serviceobjects.com/sample-code/?service=73

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/ev2/EmailValidation2.asmx

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/ev2/EmailValidation2.asmx?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. EmailValidation2 has three operations:

ValidateEmailFast – Deprecated: use ValidateEmailFast_v2
ValidateEmailFast_v2 – Validates an email address returning all of our standard flags, indicating the quality of the address, as well as other data. This check is always fast and will not perform any real-time SMTP level checks, however may still provide SMTP level information via one of our other mechanisms.
ValidateEmailFull – Deprecated: use ValidateEmailFull_v2
ValidateEmailFull_v2 – This operation has the same input/output as ValidateEmailFast. However, if we are unable to provide all the SMTP level flags, it may try to do real-time SMTP level checks. In this case it may return SMTP check information, but may take several seconds longer.
ValidateEmailFastNoNames – Deprecated: use ValidateEmailFastNoNames_v2
ValidateEmailFastNoNames_v2 – This operation is identical to ValidateEmailFast but is even faster because it omits the PossibleFirstName and PossibleLastName fields.
CorrectEmail – This operation tries to correct an email that is syntactically incorrect, or one that fails to comply with the additional rules implied by its specific domain.

Each of these operations will be described in detail later in this document.

Request Types

EV2 is a public XML web service that supports SOAP(1.1 and 1.2), POST and GET request methods. A request type is just the type of web (HTTP) request to interact with our web services.
GET – All of the input data is in the query string appended to the url. The response is simple XML.
POST – The input parameters are in the body of the request instead of the query string. The response is simple XML.
SOAP – The input parameters are in an XML SOAP message contained within the body of the request. The response is an XML SOAP message.

Analysis of Request Types

GET is the easiest method to implement by hand because you just set up the URL and query string. It is also easy to debug because you can test the URL + query string in a web browser and see the output.
POST is probably the best method to implement by hand because you do not have to know the specifics of SOAP, and is a little cleaner than passing input parameters in the query string via GET.
SOAP is the best method if you are using a platform that supports SOAP. In many programming environments you can give your Integrated Development Environment (IDE) the URL to the WSDL of a web service (https://trial.serviceobjects.com/ev2/EmailValidation2.asmx?WSDL) and it will create a proxy class to help you interact with the web service. In this case you only have to create an instance of the proxy and use its methods. This completely abstracts the programmer from any complications like sending/receiving web requests/responses as well as any XML parsing.

XML Parsing

If you are not using an environment that creates a proxy class for you to use, then you will have to parse XML. If you do have a proxy, then it uses an XML parser behind the scenes for you. Although XML parsing can be done without a parser, most programming environments provide easy access to several standard ones. We strongly recommend that you take advantage of an XML parser. These parsers may take a few more minutes to integrate if the developer is not familiar with them, but will give your application an added level of security against improper parsing. Without them it is very difficult, even for skilled programmers to write robust code that can handle all cases of XML properly. Because we have very consistent XML you could get away without this extra precaution, but we suggest you use an XML parser anyway to ensure your application is of the highest quality.

Operation Definitions

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

Important Note!
SMTP check 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, try the email again a few hours later there is a very good chance we will have acquired the information.

ValidateEmailFast_v2 / ValidateEmailFastNoNames_v2 / ValidateEmailFull_v2

These are the main operations for validating an email. They run through several checks to determine if an email is valid. If one step fails, subsequent checks cannot be done because they have been logically eliminated: if the syntax on an email fails, neither the DNS nor the SMTP check is done.

Step 1: Syntax Check – The email is tested to verify that its structure 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 2: DNS Check – The DNS or domain name check verifies that the domain exists and has a valid MX record in order to direct mail to the correct mail server. If we return unknown SMTP checks, then the DNS check is the next best thing.

Step 3: SMTP Check – Once we obtain the location of the mail server from the MX record of 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 the behavior of email servers, known as SMTP servers. Because of the growth of spam and email-mining tools, SMTP servers often respond to requests for information in defensive ways. SMTP servers will 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.

The ValidateEmailFast operations are usually faster but will occasionally return less robust data than the ValidateEmailFull operations.

ValidateEmailFast_v2 / ValidateEmailFastNoNames_v2 / ValidateEmailFull_v2 Inputs

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.

ValidateEmailFast_v2 / ValidateEmailFastNoNames_v2 / ValidateEmailFull_v2 Outputs

Name	Type	Values	Description
EmailAddressIn	String	Varies	Echo of input: EmailAddress
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.
IsRecognizedTLD	Boolean	T/F	Is the top level domain recognized by ICANN.
TopLevelDomain	String	Varies	The part after the rightmost ‘.’
TopLevelDomainDescription	String	Varies	Description of the Top Level Domain.
IsCCTLD	Boolean	T/F	Indicates if the TLD represents a specific country. For example .us implies United States.
IsSyntaxGood	Boolean	T/F	Indicates if the email is syntactically valid.
IsDomainSpecificSyntaxGood	Boolean	T/F	Indicates if the email is syntactically valid including the additional syntax rules specific to the email’s domain.
IsDNSGood	Boolean	T/F	Indicates if the domain is registered and has at least one MX record.
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.
IsFree	String	true false unknown	Indicates if the domain of the email is a public-register domain, where users can sign up for email accounts for free.
IsEstablished	Boolean	T/F	Indicates if the email is known within large lists of bulk-marketing lists.
IsAlias	Boolean	T/F	Indicates if the email matches alias rules for different sites. For example, any email with a “+” in it at gmail.com is an alias. An alias may also indicate that the email is disposable, for example anything@mailinator.com
IsBogus	Boolean	T/F	Indicates if the email is obviously bogus – such as a@a.com, asdf@asdf.com, or bgates@microsoft.com etc.
IsVulgar	Boolean	T/F	Indicates if the email address contains obvious vulgar words.
PossibleFirstName*	String	Varies	A common first name that was found in the email address. It is possible this is the user’s first name, but not guaranteed.
PossibleLastName*	String	Varies	A common last name that was found in the email address. It is possible this is the user’s last name, but not guaranteed.
IsSMSDomain**	Boolean	T/F	Indicates if the domain is a known Mail-to-SMS Gateway.
IsRole**	Boolean	T/F	Indicates if the email address appears to be a role that is designed to be anonymously managed by one or more persons.
IsGood**	Integer	0 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
IsDeliverable**	String	true false unknown	Indicates if the mail server will accept mail for the given email address.^[2]
IsBusinessAddress**	String	true	Indicates if the email address appears to be work related.^[3]

* ValidateEmailFastNoNames and ValidateEmailFastNoNames_v2 do not contain these output fields.

** Made available in version 2 operations.

[1] This value is dependent on the amount data that is available for the address. The service then analyzes the data to estimate the validity 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] Returns true only if the email appears to be a business address, returns nothing otherwise.

CorrectEmail

CorrectEmail Inputs

Name	Type	Description
EmailAddress	String	The email address you wish to correct.
LicenseKey	String	Your license key to use the service. Sign up for a free trial key at www.serviceobjects.com.

CorrectEmail Outputs

If no errors are encountered, an EmailCorrectInfo element will be returned with the following. If there is an error, an Error object will be returned (explained in next section).

Name	Type	Values	Description
EmailAddressIn	String	Varies	Echo of input: EmailAddress
EmailAddressOut	String	Varies	The corrected email address.

Errors

Anything that happens during a run of DOTS Email Validation 2 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

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 2 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. Domain Specific errors indicate that the service completed successfully but the result is not good.

DescCode	Desc
1	“The email could not be corrected.”
2	“The email could not be corrected into the form required by the specific domain.”

Frequently Asked Questions

Conclusion

Service Objects is pleased to offer you a free trial of DOTS Email Validation 2.
Sign up today for a free trial at:
https://www.serviceobjects.com/email-validation/

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

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

We welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.
www.serviceobjects.com