Docs / API - EmailOversight

API Details

EmailOversight API is built using the REST design concept. The API can only be accessed using secure HTTPs protocol using GET or POST methods. Both method types return the same API response.

IMPORTANT!

If the API is accessed via a backend server process, then the public IP of the server must be whitelisted.
If API requests are made from a client-side URL, then that URL must be whitelisted due to cross domain restrictions.
More information is available under the API/Access Control Tab in your EmailOversight user account.

EmailOversight API Services

Please sign up for an account to access our detailed API documentation which includes the various services EmailOversight offers to it’s clients. Learn more about Email Validation, Phone Validation, Address Validation and more inside your account login with quick links to all the API credentials. Read below for a full list of our API offerings:

Available APIs

Email Validation
Phone Validation
Activity Match
Address Validation
Email Append
IP Email Append
Name Append
Address Append
Zip Append
Age Append
DOB Append
Gender Append
Ethnicity Append
Data Append

IMPORTANT NOTE:

The following details pertain to EmailOversight’s Email Validation API.

API Parameters

ListId:
List IDs are located under Lists menu. List ID must be valid and belong to the user. Request will return an error if ListId is invalid.

Email:
Email address to be validated.

GET Method

This is the easiest for integration but also least secure. GET requires input parameters being passed as clear text in query
string format.

GET URL Example

GET
https://api.emailoversight.com/api/emailvalidation?apitoken={API Token}&listid={ListId}&email={Email}

For this demonstration let =>
{API Token} = 00000xx0-00×0-00×0-00xx-x00xx000xxxx

==> https://api.emailoversight.com/api/emailvalidation?apitoken=00000xx0-00×0-00×0-00xx-x00xx000xxxx&listid={ListId}&email={Email}

POST Method

This method is most secure. When using POST none of the parameters are passed as clear text.

IMPORTANT!

ApiToken is passed in the request headers and request JSON is passed as POST body.

POST URL Example

POST https://api.emailoversight.com/api/emailvalidation

Request Header Example

Request Header
“ApiToken”:”{API Token}”

For this demonstration let =>
{API Token} = 00000xx0-00×0-00×0-00xx-x00xx000xxxx

==> “ApiToken”:”00000xx0-00×0-00×0-00xx-x00xx000xxxx”

Request Body Example (JSON)

Request Body {“ListId”:{ListId},”Email”:{Email}}

For this demonstration let =>
{ListId} = 25
{Email} = “joe@testdomain.com”

==> {“ListId”:25,”Email”:”joe@testdomain.com”}

Email Validation API Response

Regardless of the method (GET or POST) the API response will be the same format (JSON).

API Response Example (JSON)(POST Method)

API Response Format { “ListId”:{ListId}, “Email”:{Email}, “ResultId”:{ResultId}, “Result”:{Result} }

For this demonstration let =>
{API Token} = 00000xx0-00×0-00×0-00xx-x00xx000xxxx
{ListId} = 25
{Email} = “joe@testdomain.com”

GET Method

https://api.emailoversight.com/api/emailvalidation?apitoken=00000xx0-00×0-00×0-00xx-x00xx000xxxx&listid={ListId}&email={Email}

POST Method

https://api.emailoversight.com/api/emailvalidation

Request Header “ApiToken”:”00000xx0-00×0-00×0-00xx-x00xx000xxxx”
Request Body {“ListId”:25,”Email”:”joe@testdomain.com”}

The resulting API response (GET and POST Methods):

{“ListId”:25, “Email”:”joe@testdomain.com”, “ResultId”:1, “Result”:”Verified”}

Email Validation Result Table


Response Code	Response Text	Description
0	Retry	Unable to establish a validation resopnse from the ISP – retry again.
1	Verified	Email address is deliverable.
2	Undeliverable	Email address does not exist, invalid, suspended, over quota or disabled.
3	Catch All	Domain of email address accepts all mail and it is impossible to determine validity. If the email address was acquired organically or you have confidence in the validity of the email address, then send at your discretion.
4	Role	Email is associated to common distribution groups. abuse@, sales@, no-reply@, test@ and etc.
5	Malformed	Email address does not conform to valid email format.
6	SpamTrap	Avoid SpamTrap emails at all cost. Those accounts are kept alive to damage sender reputation.
7	Complainer	Complainers are commonly users who like to complain after receiving email. Complaints can vary from ISP notification to cease and desist letters. In some rare cases they can also pursue litigation. These are valid addresses but we do not recommend sending mail.
9	Bot	Bots are email accounts that are maintained by bot servers for sending spam, clicking every link and other harmful or harmless activities.
10	Seed Account	Seed accounts are known email addresses that are maintained in masses for various reasons. Most commonly they are used for compliance tracking.
11	Unknown	Email address cannot be verified at the moment. Retrying later may succeed.
12	Unauthorized	Unauthorized API access. This error will be returned if IP or URL are not whitelisted and there are over 50 requests within 24 hours.
13	Disposable Email	Temporary email account that is designed to only be used few times before expiring.
20	Suppressed	Email is in known suppression list. This is only available when advanced validation is enabled on particular list.

Code Examples

JavaScript Code Examples

GET Method


            <script src="Scripts/jquery-2.1.1.js"></script>
            <script>
            function EmailValidationGet(apiToken, listId, email) {
            $.ajaxSetup({ contentType: 'application/json; charset=utf-8' });
            $.getJSON("https://api.emailoversight.com/api/emailvalidation?apitoken=" + apiToken + "&listid=" + listId + "&email=" + email, function (data) {
            }).done(function (data) {
                var str = JSON.stringify(data, null, 2);
                //Usable Json Object
                var obj = JSON.parse(str);
            })
                .fail(function (jqxhr, textStatus, error) {                                        
                    
                    //Available fields
                    console.log(jqxhr["responseJSON"]);
                    console.log(jqxhr["readyState"]);
                    console.log(jqxhr["responseText"]);
                    console.log(jqxhr["status"]);
                    console.log(jqxhr["statusText"]);
                });
        }
        
        </script>

POST Method


    <script src="Scripts/jquery-2.1.1.js"></script>
    <script>
    function EmailValidationPost(apiToken, listId, email) {
        
            var requestJson = { 'ListId':listId, 'Email':email };
    
            $.ajax("https://api.emailoversight.com/api/emailvalidation", {
            type: "POST",
            data: JSON.stringify(requestJson),
            contentType: 'application/json; charset=utf-8',
            dataType: 'json',
            headers: GetHeaders(),
            success: function (data) {
                
                var str = JSON.stringify(data, null, 2);
                //Usable Json Object
                var obj = JSON.parse(str);
            },
            error: function (jqxhr, textStatus, error) {
                
                    //Available fields
                    console.log(jqxhr["responseJSON"]);
                    console.log(jqxhr["readyState"]);
                    console.log(jqxhr["responseText"]);
                    console.log(jqxhr["status"]);
                    console.log(jqxhr["statusText"]);
            }
        });
    
        }
        
    function GetHeaders(){
        return { "ApiToken": "00000xx0-00x0-00x0-00xx-x00xx000xxxx" };
    }
    
        </script>

C# Code Examples

GET Method


        using System.Net.Http;
        using System.Net.Http.Headers;
        
        public class EmailValidationRequest
        {
        public int ListId { get; set; }
        public string Email { get; set; }
        }
        
        public class EmailValidationResponse
        {
        public int ListId { get; set; }
        public string Email { get; set; }
        public int ResultId { get; set; }
        public string Result { get; set; }
        }
        
        static string  _apiURL = "https://api.emailoversight.com/api/emailvalidation";       
        static string  _apiToken = "00000xx0-00x0-00x0-00xx-x00xx000xxxx";
        
        public static EmailValidationResponse ValidateEmail(EmailValidationRequest request, int timeoutInSeconds, Logger log)
        {
        EmailValidationResponse resps = new EmailValidationResponse();
        using (var client = new HttpClient())
        {
            try
            {
                client.BaseAddress = new Uri(string.Format("{0}?apitoken={1}&listid={2}&email={3}", _apiURL, _apiToken, request.ListId, request.Email));
                client.DefaultRequestHeaders.Accept.Clear();
                client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
                client.Timeout = new TimeSpan(0, 0, 0, timeoutInSeconds);
                HttpResponseMessage response = client.GetAsync("").Result;
                
                if (response.IsSuccessStatusCode)
                {
                    resps = response.Content.ReadAsAsync<EmailValidationResponse>().Result;
                }
                else
                {
                    // Incase of an error
                    log.Trace(response.ReasonPhrase);                 
                }
            }
            catch (Exception ex)
            {
                log.Trace(ex);
            }
        }
        return resps;
        }

POST Method


        using System.Net.Http;
        using System.Net.Http.Headers;
        
        public class EmailValidationRequest
        {
        public int ListId { get; set; }
        public string Email { get; set; }
        }
        
        public class EmailValidationResponse
        {
        public int ListId { get; set; }
        public string Email { get; set; }
        public int ResultId { get; set; }
        public string Result { get; set; }
        }
        
        static string  _apiURL = "https://api.emailoversight.com/api/emailvalidation";       
        static string  _apiToken = "00000xx0-00x0-00x0-00xx-x00xx000xxxx";
        
        public static EmailValidationResponse ValidateEmail(EmailValidationRequest request, int timeoutInSeconds, Logger log)
        {
        EmailValidationResponse resps = new EmailValidationResponse();
        using (var client = new HttpClient())
        {
            try
            {
                client.BaseAddress = new Uri(_apiURL);
                client.DefaultRequestHeaders.Accept.Clear();
                client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
                client.DefaultRequestHeaders.Add("ApiToken", _ApiToken);
                client.Timeout = new TimeSpan(0, 0, 0, timeoutInSeconds);
                HttpResponseMessage response = client.PostAsJsonAsync("", request).Result;
                
                if (response.IsSuccessStatusCode)
                {
                    resps = response.Content.ReadAsAsync<EmailValidationResponse>().Result;
                }
                else
                {
                    // Incase of an error
                    log.Trace(response.ReasonPhrase);                 
                }
            }
            catch (Exception ex)
            {
                log.Trace(ex);
            }
        }
        return resps;
        }