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
Email Validation 3 Java Code Snippet
Email Validation 3 PHP Code Snippets
Email Validation 3 RoR Code Snippets
Email Validation 3 Python Code Snippets
Email Validation 3 ColdFusion Snippet
Email Validation 3 VB Snippet
Email Validation 3 Apex Code Snippet
Email Validation 3 TSQL Code Snippet
Email Validation 3 C# Rest Code Snippet
Email Validation 3 Java Rest Code Snippet
Email Validation 3 PHP Rest Code Snippets
Email Validation 3 RoR Rest Code Snippets
Email Validation 3 PythonCode Snippets
Email Validation 3 ColdFusion Code Snippet
Email Validation 3 VB Rest Snippet
Email Validation 3 TSQL Rest Code Snippet

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#

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
XML Request: 
https://trial.serviceobjects.com/ev3/web.svc/xml/ValidateEmailInfo?EmailAddress=support@serviceobjects.com&AllowCorrections=true&Timeout=500&LicenseKey=yourDevKey


XML Response

ValidateEmailFull Example Request and Response


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

ValidateEmailFast Example Request and Response

 

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


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


XML Response

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
URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Full/NoCorrections/support@serviceobjects.com/yourDevKey?format=xml
XML Response

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
URL Request: 
https://trial.serviceobjects.com/ev3/api.svc/ValidateEmailInfo/Fast/NoCorrections/support@serviceobjects.com/yourDevKey?format=xml
XML 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:

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.

 

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.

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 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.

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 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.

Labels
  • None