- List of Operations
- Operation Definitions
- Outputs Values
- Frequently Asked Questions
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.
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 firstname.lastname@example.org 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.
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 email@example.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:
A test page for the web service can be found here:
The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
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.
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 firstname.lastname@example.org.
ValidateEmailAddress Example Request and Response
ValidateEmailFull Example Request and Response
ValidateEmailFast Example Request and Response
ValidateEmailFullNoCorrections Example Request and Response
ValidateEmailFastNoCorrections Example Request and Response
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:
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:
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:
The same as ValidateEmailFull but the service will not attempt to correct the email address.
The same as ValidateEmailFast but the service will not attempt to correct the email address.
This section defines the input, output and behavior of the web services in EV3.
ValidateEmailAddress (Recommended Operation)
The email address you wish to validate.
|AllowCorrections||String||Accepts 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.|
|Timeout||String||This 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.|
Your license key to use the service.
*All input values are required
ValidateEmailFull & ValidateEmailFast
The email address you wish to validate.
Your license key to use the service.
|An estimate on the validity of the email address. |
0 = Email is Good
1 = Email is Probably Good
2 = Unknown
3 = Email is Probably Bad
4 = Email is Bad
|Indicates if the mail server will accept mail for the given email address.|
Echo of input: EmailAddress
|EmailAddressOut||String||Varies||The cleaned and corrected email. This is the email that is validated.|
|EmailCorrected||Boollean||T/F||Indicates if any corrections or modifications were made to the email address.|
The part to the left of the '@' symbol. Also known as the local part or the username.
The part to the right of the '@' symbol. The location to which the email address will be sent.
The part after the rightmost '.'
Description of the Top Level Domain.
Indicates if the email's mail server is operational.
Indicates if the mail server will accept mail to any box in that domain (*@domain).
Indicates if the mail server will accept mail to the specific box.
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.
Contains the warning flag(s) that corresponds to the Warning Codes. Returns zero or more warning flags in a comma-separated list.
|NotesCodes||String||0-6||Displays additional notes about the email that were found during the validation process. Returns zero or more numerical note codes in a comma-separated list.|
|NotesDescription||String||Varies||Contains the note flag(s) that corresponds to the Notes Codes. Returns zero or more notes flags in a comma-separated list.|
 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.
 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.
 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.
|0||UnrecognizedTLD||Indicates if the top-level-domain is not recognized by ICANN.|
|1||InvalidSyntax||Indicates if the email is syntactically invalid.|
|2||InvalidDomainSpecificSyntax||Indicates if email is syntactically invalid for the given domain.|
Indicates if the domain is unregistered or it does not have at least one MX or A record configured to relay email.
|4||NoMXRecords||Indicates that the registered DNS does not have an MX record.|
Indicates that the email address is known to be in bulk marketing lists.
Indicates if the email address is believed to be an alias address.
Indicates if the email address is believed to be a bogus email. For example, email@example.com.
Indicates if the email address is believed to be a bogus SMS domain address.
Indicates if the email address is believed to contain garbage-like keyboard strokes and/or garbage-like characters.
Indicates if vulgar words or content are found in the email address.
Indicates if the mailbox is currently full and unable to receive any new messages.
Indicates if the mailbox is reported by the hosting mail server as being busy and unable to currently accept new messages.
|13||DisposableEmail||Indicates 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.|
Indicates if the mailbox is believed to be a spam trap.
Indicates if the email address is known to have participated in spam-like activities.
Indicates if the domain was found to be in one or more blacklists.
Indicates if the email address has been identified as a known complainer of receiving unsolicited mail. ** Coming Soon **
|18||KnownGreylister||Indicates 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.|
|19||OptInRequired||Indicates if the mail server requires opting-in to send and receive messages.|
|20||IsWhiteListOnly||Indicates if the mail server only relays messages for users that are whitelisted.|
|21||ConnectionRefused||Indicates if the mail server refuses to accept an SMTP connection.|
|22||Email is Bad - Subsequent checks halted.||Indicates that the email address failed a critical check, such as SMTP verification.|
|23||Bot||Indicates 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.
|0||CCTLD||Indicates if the top-level-domain (tld) represents a specific country. For example ".us" implies United States.|
|1||Free||Indicates if the domain of the email is a public-register domain, where users can sign up for email accounts for free.|
Indicates if the domain is a known Mail-to-SMS Gateway.
|3||Role||Indicates if the email address appears to be a role that is designed to be anonymously managed by one or more persons.|
Indicates if the email address appears to be work related.
|5||GreyListed||Indicates if the mail server responded with a known greylist tactic.|
Indicates that the mail server may be temporarily unavailable or too busy to respond.
|7||ServerConnectTimeout||Indicates that a connection to the recipient mail server could not be established.|
|8||MailBoxTimeout||Indicates that the connection to the mail server timed out when trying to verify the email address.|
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.
|10||SlowMailServer||Indicates 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.|
|***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.|
|***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.|
***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.
|***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.|
|15||SMTPCheckTimeout||Indicates that SMTP communication did not finish in the allotted time. It is recommend to increase the timeout time and try again.|
|16||TLS||***Coming Soon: Indicates that the recipient mail server supports Transport Layer Security (TLS) connections for encrypted email communication.|
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:
There are four error types described below.
Standard Across All Gen2 Web Services
Service Objects Fatal
Error type 1: Authorization
Theses are standard to all Generation 2 DOTS Web Services.
Unknown authorization error.
Please provide a valid license key for this web service.
The daily allowable number of transactions for this license key has been exceeded.
The monthly allowable number of transactions for this license key has been exceeded.
The total allowable number of transactions for this license key has been exceeded.
There are not enough transactions available. Check your daily/monthly transaction limits.
This license key has not yet been activated.
This license key has expired.
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.
You must input an email address in the EmailAddress field.
You must input a license key in the LicenseKey field.
|3||You must enter True or False in the AllowCorrections field.|
|4||Invalid value for AllowCorrections. Please enter True or False.|
|5||You must input a time out value in the timeout field.|
|6||Invalid 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.
Unhandled error. Please contact Service Objects.
Error type 4: Domain Specific
Domain specific errors represent the common errors seen in Service Objects services.
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.
Why do I get SMTP level info for most email addresses, but sometimes not for others like yahoo and hotmail addresses?
In order to get the SMTP box level check we must hit the mail server in real-time, or somehow already know that it is good. The problem is that we have an important company policy that prevents us from making too many requests, within a certain time period, to the same mail server. So even though we make many requests to a common mail server like hotmail.com, we do not always have enough available requests at that time to do the SMTP level checks.
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. Note: This does not mean we will always be able to do this, especially with common domains where we may have exceeded the maximum number of requests.
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 firstname.lastname@example.org 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.
Does your service hammer popular mail servers like aol.com with real-time SMTP requests? Do you run the risk of getting blocked from any mail servers?
We have a company policy to limit the number of requests per time period to a specific mail server. So to answer the question, yes we hit common mail servers often but never more than our limit. Our limit is modestly set so that we do not overly disturb any mail servers. Because we carefully limit and monitor the requests to all mail servers we are very unlikely to ever get blocked from any mail server. In the unlikely event that we do get blocked, we have backup plans in place to insure that our service will continue to return top quality 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 email@example.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).
Service Objects is pleased to offer you a free trial of DOTS Email Validation 3.
We want to hear from you! We're always looking to improve our developer guides.
Please email your suggestions to firstname.lastname@example.org.