Real Time Verification API Documentation

(1)

email-checker.com

(2)

(3)

1 Product Overview 3 1.1 Product Overview . . . 3 2 Quick Start 5 2.1 Quick Start . . . 5 3 Features 7 3.1 Features. . . 7 4 Technical Specification 11 4.1 Technical Specification. . . 11 5 Installation 13 5.1 Installation . . . 13

6 Configuration And Usage 15

6.1 Configuration And Usage . . . 15

7 Integration 19

7.1 Integration . . . 19

8 Plugins 21

8.1 Plug-ins. . . 21

9 FAQs 23

9.1 Frequently Asked Questions . . . 23

10 Status Codes 27

10.1 Email Verification Response Codes For API V1. . . 27

11 Integration Examples 31

11.1 Integration Examples. . . 31

12 Glossary 49

(4)

(5)

• emailyoyo.com • emailcleansing.com • bulkemailverifier.com

For customers using ourAPIfor the first time, please see our most up to dateEmail Verification API.

Our email verificationAPIwill help your business reduce costs by eliminating bad email addresses from entering your information systems.

(6)

Real Time Email Verification API Documentation, Release 1.0.17

(7)

Product Overview

1.1 Product Overview

1.1.1 Why Email Address Verification?

Sending emails to non-existent addresses is never a good idea for many reasons including:

Damaging the reputation of yourESPinfrastructure (IP addresses) Many ESPs will have maximum hard bounce thresholds. Exceed these and your account could be closed.

Bad emails in a list negatively affects deliver-ability rates ABlock Listcan keep track of failed deliveries (e.g. bad email address) at a particular domain. Too many failed deliveries can raise some flags thus raising the risk of your email campaign being flagged as spam.

Processing hard bounces means wasted time An email sent to a bad or non-existent email address results in a bounce message coming back. Someone or something (e.g. automated software) is required to remove the bounces from a email list so as to avoid sending to bad addresses next time.

Tip: Cleansing bad emails from a list using email verification technology before embarking on an emailing campaign significantly reduces the above challenges.

1.1.2 Product Description

emailhippo.comoffers data cleansing services specifically for email addresses. Offering a fully cloud based solution,

emailhippo.comprovides fast, reliable and accurate email verification.

With unrivalled coverage in all areas (including traditionally hard to verify email addresses such as Hotmail and Yahoo), emailhippo.comis the natural choice for customers requiring good coverage in their applications for both B2BandB2Cemail addresses.

1.1.3 Possible Applications for Email Address Verification API

• If you operate a lead generation web site, blog or forum make it harder for users to sign up with false emails. • For e-commerce checkouts, make sure customers receive their order notifications by preventing invalid emails

(8)

• For software vendors where email addresses are captured as part of the on-boarding process, integrate full email verification as a value-add for your service.

• Withemailhippo.com, there is no need any more to take incorrect email addresses and wait for them to bounce!

1.1.4 How To Get Started

To get startedrequest a trial key.

(9)

Quick Start

2.1 Quick Start

This quick start guide is designed to get you up and running as fast as possible. Please follow the steps below in sequence:

2.1.1 1) Get a License Key

Request a trial key.

2.1.2 2) Try it!

Plug your license key into the following

https://api1.27hub.com/api/a/v1?key=INSERTYOURLICENSEKEY&email=test@tester.com

Paste the url above into your browser and watch the response come back as follows: { "status":"Bad", "additionalStatus":"MailboxDoesNotExist", "emailAddressProvided":"test@tester.com", "emailAddressChecked":"test@tester.com", "emailAddressSuggestion":"" }

Note: Internet Explorer may prompt to download the file instead of simply displaying it on screen. This is a quirk of Internet Explorer and not an issue with theAPI. We do not recommend Internet Explorer for testing with theAPI. Instead, use Chrome or Firefox - both will display the results on screen correctly!

2.1.3 3) Next Steps

• Configuration And Usage • Integration

(10)

(11)

Features

3.1 Features

3.1.1 > 99.9% Service Availability

Fully load balanced and automatic fail-over systems dispersed across multiple data centers in multiple regions deliver enterprise grade resilience.

3.1.2 Fanatical Service Quality Management (SQM)

emailhippo.comoperational staff obsessively monitor services to ensure the best possible uptime and coverage. Uptime and functional correctness is actively monitored on a minute by minute basis from multiple data centers dispersed across North America, Europe and South East Asia.

3.1.3 Multi Factor Verification

Progressive verification using multiple verification processes including: • Syntax checking

• DNS checking • Mailbox checking

3.1.4 Unrivalled Coverage

With more than 5 years experience and the benefit of owning our own software stack,emailhippo.comhas refined its services over the years to provide good coverage not only of the easierB2Bdomains but also the more technically trickyB2Cdomains including:

• Hotmail • Yahoo • AOL • Yandex

(12)

3.1.5 Unrivalled Integration

RESTfulendpoints integrate with pretty much anything these days.emailhippo.comnot only supports server to server integration over REST but server to client integration with full support forCORS.CORSis available in most mod-ern web browsers and allows rich, client side development using only HTML and JavaScript (jQuery or AngularJS recommended).

SeeIntegrationfor tested integration examples using a wide range of languages including PHP, Java, .NET, jQuery and AngularJS).

3.1.6 Spam Trap Detection

After many years R&D,emailhippo.comhas developed various “secret sauces” that can effectively detect and eliminate spam traps from several well knownBlock List.

3.1.7 Disposable Email Address Detection

Detect and eliminateDEA.

3.1.8 Unrivalled Performance

Strategic data centers in North America and Europe, aggressive caching and cloud based auto-scaling deliver outstand-ing performance. Typical queries are answered between 0.2 to 1.5 seconds.

Note: SeeTechnical Specification

3.1.9 API Based Email Verification

Every plan includes authentication systems based onACLandLicense Keybased access.

Domain basedACLauthentication is typically used for client script integrations (e.g. jQuery or AngularJS). Domain licenses are tied into a single domain (e.g. www.mydomain.com).

License Keybased authentication is typically used for server to server integrations.

3.1.10 Error Correction

No more “fat finger” syndrome! OurAPIhas an optional feature to remove certain invalid characters such as spaces, slashes etc.

3.1.11 Common Typo Handling

emailhippo.comalso searches for common typos and suggest alternatives. E.g. jim99@hotmail.cmis more likely to bejim99@hotmail.comsoemailhippo.comwill validate what the user has entered, but provide you with the more likely alternative suggestion too.

(13)

3.1.13 Thoughtful Versioning

Endpoints are “versioned”. This means thatemailhippo.comcan continue to release new functionality without “break-ing” existing clients committed to integrating with our systems on legacy endpoints.

3.1.14 What it does

emailhippo.comis used to check email addresses in real-time. Not only are syntax and domain checked, but that the user mailbox is available too. This is the only way to know for sure if an email address is valid.

Additionally identified as part of the email verification process is extra information including: • DEA.

• Spam Trap.

3.1.15 How it works

Email addresses are verified using various filters and processes. As a high level overview, an email address submitted for verification goes thorough the following filters:

Syntax A basic inspection of the syntax of the email address to see if it looks valid. Work is done only using server CPU (Central Processing Unit) based on simple pattern matching algorithms.

DNS A Verifies a domain exists inDNS. Domains that do not exist inDNScannot have mail servers or email boxes. DNSchecks are performed over the network.

DNS MX VerifyMXrecords usingDNS. Domains that do not haveMXrecords, have no mail servers and therefore no valid email boxes.

MXchecks are performed over the network. MailBox Verify email boxes withSMTPchecks.

Connect to mail server and performSMTPprotocol to verify if mail box exists. This is the deepest level of verification. It is performed over the network.

(14)

(15)

Technical Specification

4.1 Technical Specification

4.1.1 Infrastructure

Manufacturer emailhippo.com

Uptime > 99.9%

Response time >0.2seconds < 8 seconds. Typical response time 0.7 seconds. Throughput and concurrency > 100 TPS (Transactions Per Second)

Integration RESTful GET over HTTP(S)

Authentication Key or Domain based ACL (Access Control List)

Infrastructure Geographically dispersed data centers, auto load balance / failover

4.1.2 Application

Syntax checking? yes

DNS A checking? yes

DNS MX checking yes

Mailbox checking yes

Reporting / charts? yes

Versioning supported? yes

B2B (Business to Business) coverage? yes

Hotmail coverage? yes

Yahoo coverage? yes

AOL coverage? yes

Yandex coverage? yes

Secure? yes. HTTPS supported.

Spam trap detection? partial

Illegal character detection yes

Typo detection yes

DEA (Disposable Email Address) detection? yes

Reporting charts yes

Server to browser client supported? yes

Server to server supported? yes

(16)

(17)

Installation

5.1 Installation

There is no software to install. emailhippois Software as a Service exposed as a simple RESTfulservice that is available to anything connected to The Internet.

(18)

(19)

Configuration And Usage

6.1 Configuration And Usage

6.1.1 Authentication

Each call to theAPImust be authenticated. Authentication with the API is performed by either: • ACL.

• License Key.

6.1.2 Accessing the API using key authentication

Access theAPIat:

https://api1.27hub.com/api/a/v1?key=yourapikey&email=test@tester.com Sending the following parameters

:-Figure 1 - REST Request Variables

Parameter Value

key your unique API key supplied by us required

email the email address to be validated required

correct 1 - this will remove certain invalid

characters.

0 - this will leave the email un-touched.

optional

Note: Need a license key?Click here.

6.1.3 Accessing the API using ACL authentication

https://api1.27hub.com/api/b/v1?email=test@tester.com

(20)

Note: ForACLbased authentication, it is not necessary to include the license key in the request. Other parameters (e.g. ‘correct’) are supported as in the key based example as inFigure 1 - REST Request Variables.

6.1.4 Responses

Note: For a full definition of possible responses, seeEmail Verification Response Codes For API V1. You will receive back the following values in the response.

Figure 2 - Responses

Response Description Example values

status The validation result ‘Ok’, ‘Bad’,

‘Unknown’ additionalStatus Additional information for BAD and UNKNOWN results

NoMxServers-Found

emailAddressPro-vided

The exact email address passed to the API including obvious typos and errors

test@tester.com

emailAddress-Checked

The actual email address validated test@tester.com

emailAddressSug-gestion

A suggested alternative if a common typo was noticed e.g. if

‘fred@hotmail.cm‘ was provided

fred@hotmail.com

Note: Example response for email address test@tester.com The URL passed to the API is

:-https://api1.27hub.com/api/a/v1?key=yourapikey&email=test@tester.com

The response would be :-{ "status":"Bad", "additionalStatus":"MailboxDoesNotExist", "emailAddressProvided":"test@tester.com", "emailAddressChecked":"test@tester.com", "emailAddressSuggestion":"" }

6.1.5 The ‘correct’ Parameter

Optionally, you can also use the ‘correct’ parameter to remove certain invalid characters such as spaces, slashes, square brackets etc. Example using the ‘correct’ parameter. The user enters an email address john99]@gmail.com Here is the API call that would be made

:-http://api1.27hub.com/api/a/v1?key=yourapikey&email=john99]@gmail.com&correct=1

emailhippo.comwill automatically remove the invalid character ‘]’ and send the corrected version through for valida-tion. Example results based on the above API call

(21)

"emailAddressChecked":"john99@gmail.com", "emailAddressSuggestion":""

}

6.1.6 Additional Status Information

When an email address is returned with a status of Bad or Unknown we return the detailed reason as part of the response in the additionalStatus value. For a full list of additional status values, please refer to Email Verification Response Codes For API V1.

6.1.7 Sandbox

A sandbox environment is available to assist customers with testing, evaluation and integration. The sandbox url is: https://api1.27hub.com:443/api/a/v1/sandbox

There is no charge for use and your live quota is not affected. No emails are verified in the sandbox and responses are hard coded.

For a full list of hard coded test cases, please seehere.

6.1.8 Firewall

If you need to enable firewall rules based on IP addresses, you will need to add the following addresses, for ports 80 and 443, to your firewall rules:

• 23.96.209.155 • 23.98.64.158 • 191.235.208.12 • 137.117.224.218

(22)

(23)

Integration

7.1 Integration

(24)

(25)

Plugins

8.1 Plug-ins

8.1.1 jQuery Validation Plug-in

jQuery Plugin is a generic jQuery library has been constructed to use RESTful email verification services from www.email-checker.com.

(26)

(27)

FAQs

9.1 Frequently Asked Questions

9.1.1 How can I get a key?

Click hereto request a license key.

9.1.2 How do I call the API?

Make a simple GET request to the endpoint. For example, to query email address anyone@yourdomain.com with license key ABCD1234 call:

https://api1.27hub.com/api/a/v1?key=ABCD1234&email=anyone@yourdomain.com

9.1.3 What comes back from the API?

AJSONbased response similar to:

{ "status":"Bad", "additionalStatus":"MailboxDoesNotExist", "emailAddressProvided":"anyone@yourdomain.com", "emailAddressChecked":"anyone@yourdomain.com", "emailAddressSuggestion":"" }

Note: For a detailed explanation of response codes, please seeEmail Verification Response Codes For API V1.

9.1.4 How can I integrate the API with my solution?

We have tested, detailed integration examples using a wide range of technologies and languages including Java, PHP, .NET, jQuery and Angular. Please seeIntegrationfor more information.

(28)

9.1.5 How reliable is the API?

> 99.9% average availability.

9.1.6 Does the system get slower when it’s busy?

No. All infrastructure is hosted in cloud based platforms with automatic scaling enabled. Automatic scaling kicks in at busy times to provide more hardware resources to meet demand.

9.1.7 Can it do Hotmail?

Yes.

9.1.8 Can it do Yahoo?

Yes. Based on our own internal testingemailhippo.comis currently the only email verification service to offer effective and repeatable coverage for Yahoo addresses.

9.1.9 Can it do Yandex?

Yes it can.

9.1.10 Can it find spam traps?

Partially.

ASpam Trapis a moving target. In theory (and indeed in practice) anyone can setup aBlock Listand start putting spam traps into the wild.

emailhippo.comhasSpam Trapdetection capabilities that covers several of the well known block lists. Whilst it is not possible to deliver 100% coverage of all spam traps from all block lists,emailhippo.comprovides the bestSpam Trap detection capabilities available.

9.1.11 How does it work?

At a basic conceptual level, the process of verifying email addresses is very simple. Google for “Send email using telnet” for a quick and general overview of how it’s done. To verify an email address without sending an email, simply go as far as the “RCPT TO” stage and parse the response code. That’s the easy bit and can be accomplished in just a couple of dozen lines of a PHP script!

The hard bit is dealing with mail services that are intrinsically configured to work against the process of email verifica-tion or any similar SMTP based activity. The reason that any email /SMTPprocess is difficult from a client perspective is that mail services need to protect themselves from an ever increasing landscape of abuse including spam andDDoS attacks.

emailhippo.com‘s strength in dealing with the “hard bit” of email verification comes from years of experience in doing email verification together with our complete ownership of ourSMTPverification software stack together with an extensive cloud based infrastructure. That’s whyemailhippo.comcan do the “hard bits” best and offer outstanding coverage on the more difficult domains such as Yahoo and Hotmail.

(29)

9.1.13 Will anyone know that I am verifying their email address?

No. It’semailhippo.cominfrastructure that does the work.

9.1.14 Your service says an address is OK and I know it’s Bad (or vice versa)?

emailhippo.comqueries mail servers in real time. Mail servers respond with one of 2 possible answers for a given email address:

• Yes, the email address exists - SMTP code 2xx • No, the email address doe not exist - SMTP code 5xx

emailhippo.comuses the above response codes to determine if an email address is valid or not and reports this back to you.

This method of determining email address validity works in >99% cases. However, nothing is guaranteed. In a small number of cases it is possible for a mail server to report one thing on email verification and do something different on trying to deliver an email to the email address verified.

At the time of verification the mail server would have reported Yes/No, however this may have been due to an error within the target mail server and the opposite may have been true. This is rare, but it can happen. If this was a temporary error within the target mail server, please note that this result may be remembered by our system for a few hours.

For another example, say we take an email address of “this.seems.to.verify@hotmail.com” to send to. We are sending from a fictitious email address “my.sending.account@gmail.com”.

“this.seems.to.verify@hotmail.com” reports with status code of “OK” from the email verificationAPI. However, when you send an email to “this.seems.to.verify@hotmail.com”, the email bounces. Further inspection of the bounced email Non Delivery Report (NDR) headers show something like the following:

Delivered-To: my.sending.account@gmail.com

Received: by 10.107.174.134 with SMTP id n6csp24867ioo; Sat, 6 Jun 2014 03:57:29 -0800 (PST)

X-Received: by 10.202.4.5 with SMTP id 5mr1335105oie.22.1417867048986; Sat, 06 Jun 2014 03:57:28 -0800 (PST)

Return-Path: <>

Received: from SNT004-OMC2S34.hotmail.com (snt004-omc2s34.hotmail.com. [65.55.90.109]) by mx.google.com with ESMTPS id ws5si21632759obb.102.2014.12.06.03.57.28 for <my.sending.account@gmail.com>

(version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 6 Jun 2014 03:57:28 -0800 (PST)

Received-SPF: none (google.com: SNT004-OMC2S34.hotmail.com does not designate permitted sender hosts) client-ip=65.55.90.109; Authentication-Results: mx.google.com;

spf=none (google.com: SNT004-OMC2S34.hotmail.com does not designate permitted sender hosts) smtp.mail=

Received: from SNT004-MC2F40.hotmail.com ([65.55.90.73]) by SNT004-OMC2S34.hotmail.com over TLS secured channel with Microsoft SMTPSVC(7.5.7601.22751); Fri, 6 Jun 2014 03:57:28 -0800

From: postmaster@hotmail.com To: my.sending.account@gmail.com Date: Fri, 6 Jun 2014 03:57:28 -0800 MIME-Version: 1.0

(30)

X-DSNContext: 335a7efd - 4481 - 00000001 - 80040546 Message-ID: <mjZ7zgTpi00029250@SNT004-MC2F40.hotmail.com> Subject: Delivery Status Notification (Failure)

Return-Path: <>

X-OriginalArrivalTime: 06 Jun 2014 11:57:28.0142 (UTC) FILETIME=[CEAD2EE0:01D0114B]

This is a MIME-formatted message.

Portions of this message may be unreadable without a MIME-capable mail program.

--9B095B5ADSN=_01D010AABCE2C5CC0008C930SNT004?MC2F40.ho Content-Type: text/plain; charset=unicode-1-1-utf-7

This is an automatically generated Delivery Status Notification. Delivery to the following recipients failed.

this.seems.to.verify@hotmail.com

The email header of the NDR shows that Hotmail thinks the email address is invalid as far as sending to this address is concerned. However, Hotmail reports that the same email address is valid as far as the email verification activity performed byemailhippo.com.

The discrepancy in verification results versus mail send is with the Hotmail infrastructure reporting one thing but doing the exact opposite. This behaviour occasionally (particularly from Hotmail) is seen in a small amount of cases and is attributable to internal Hotmail (or other mail services) system anomalies.

The majority (>99%) of email verification status versus mail send is consistent. However there are some edge cases caused by system faults in the mail service providers themselves. For these small number of cases, there is nothing that can be done at the email verification stage.

(31)

Status Codes

10.1 Email Verification Response Codes For API V1

A response is a message consisting of a standardHTTPheader and body. The body of the message contains the detail of the message (e.g. theJSONdata with email verification detail). The header of the message contains generalHTTP information such asHTTPstatus codes.

Response Body Content

• Main Status Response Codes • Additional Status Codes Response Header

• HTTP Status Codes

10.1.1 Response Body Content

Main Status Response Codes

Ok Verification passes all checks including Syntax,DNS,MX, Mailbox, Deep Server Configuration,Grey Listing

Bad Verification fails checks for definitive reasons (e.g. mail box does not exist)

Unknown Conclusive verification result cannot be achieved due to mail server configuration or anti-spam measures. See table “Additional Status Codes”.

Additional Status Codes

None No additional information is available.

This status differs from a TransientNetworkFault as it should not be retried (the result will not change).

There are a few known reasons for this status code for example the target mx record usesOffice 365 or a mail provider implementing custom mailbox shutdowns.

(32)

DomainIsInexistent The domain (i.e. the bit after the ‘@’ character) defined in the email address does not exist, according toDNSrecords.

A domain that does not exist cannot have email boxes. A domain that does not exist cannot have email boxes.

DomainIsWellKnownDea The domain is a well known Disposable Email AddressDEA.

There are many services available that permit users to use a one-time only email address. Typically, these email addresses are used by individuals wishing to gain access to content or services requiring registration of email addresses but same individuals not wishing to divulge their true identities (e.g. permanent email addresses).

DEAaddresses should not be regarded as valid for email send purposes as it is unlikely that messages sent to DEA addresses will ever be read.

MailboxFull The mailbox is full.

Mailboxes that are full are unable to receive any further email messages until such time as the user empties the mail box or the system administrator grants extra storage quota.

Most full mailboxes usually indicate accounts that have been abandoned by users and will therefore never be looked at again.

We do not recommend sending emails to email addresses identified as full. MailboxDoesNotExist The mailbox does not exist.

100% confidence that the mail box does not exist.

NoMxServersFound There are no mail servers defined for this domain, according toDNS. Email addresses cannot be valid if there are no email servers defined inDNSfor the domain. ServerDoesNotSupportInternationalMailboxes The server does not support international mailboxes.

International email boxes are those that use international character sets such as Chinese / Kanji etc. International email boxes require systems in place forPunycodetranslation.

Where these systems are not in place, email verification or delivery is not possible. For further information seePunycode.

ServerIsCatchAll The server is configured for catch all and responds to all email verifications with a status of Ok.

Mail servers can be configured with a policy known as Catch All. Catch all redirects any email address sent to a particular domain to a central email box for manual inspection. Catch all configured servers cannot respond to requests for email address verification.

Success Successful verification.

100% confidence that the mail box exists.

TooManyAtSignsFound Too many ‘@’ signs found in email address. Only one ‘@’ character is allowed in email addresses.

Unknown The reason for the verification result is unknown.

TransientNetworkFault A temporary network fault occurred during verification. Please try again later. Verification operations on remote mail servers can sometimes fail for a number of reasons such as loss of network connection, remote servers timing out etc.

One other possible cause of a temporary fault isGrey Listing.

(33)

and this may affect your daily quota.

PossibleSpamTrapDetected A possible spam trap email address or domain has been detected.

Spam traps are email addresses or domains deliberately placed on-line in order to capture and flag potential spam based operations.

Our advanced detection heuristics are capable of detecting likely spam trap addresses or domains known to be associated with spam trap techniques.

We do not recommend sending emails to addresses identified as associated with known spam trap behaviour.

Sending emails to known spam traps or domains will result in yourESPbeing subjected to email blocks from aDNS Block List..

AnESPcannot tolerate entries in aBlock List(as it adversely affects email deliver-ability for all customers) and will actively refuse to send emails on behalf of customers with a history of generating entries in aBlock List.

10.1.2 Response Header

HTTP Status Codes

In additional to the application level codes (seeMain Status Response CodesandAdditional Status Codes) returned in theHTTPmessage body,HTTPstatus codes are returned in theHTTPheader.

200 Call successful.

304 The cached copy on the client is up to date. Resource not transferred. Use this with client side “If-Modified-Since” request for efficient caching. Caching is available for bothHTTPand HTTPS options.

400 Bad request. The server could not understand the request. Perhaps missing a license key or an email to check? Conditions that lead to this error are: No license key supplied, no email address supplied, email address > 255 characters, license key in incorrect format.

401 Possible reasons: The provided license key is not valid, the provided license key has expired, the provided license key is not permitted for use from this domain, you have reached your quota capacity for this account, this account has been disabled.

500 An error occurred on the server. Possible reasons are: license key validation failed or a general server fault.

(34)

(35)

Integration Examples

11.1 Integration Examples

11.1.1 Server Examples

PHP

<?php

// URL which should be requested

$url = 'http://api1.27hub.com/api/a/v1';

$apikey = 'YOUR API KEY'; // API Key

$email = 'Email Address to Test'; // Email to test

// jSON String for request

$url .= "?email=$email&key=$apikey";

// Initializing curl

$ch = curl_init( $url );

if($ch == false) {

die ("Curl failed!");

} else {

// Configuring curl options

$options = array(

CURLOPT_RETURNTRANSFER => true,

CURLOPT_HTTPHEADER => array('Content-type: application/json') );

// Setting curl options

curl_setopt_array( $ch, $options );

// Getting results

(36)

Real Time Email Verification API Documentation, Release 1.0.17 echo "$result"; } ?> C# #region Usings using System; using System.IO; using System.Net; #endregion /// <summary> /// The program. /// </summary>

internal class Program

{

#region Constants

/// <summary> /// The api url. /// </summary>

private const string ApiUrl = @"http://api1.27hub.com/api/a/v1"; /// <summary>

/// 0 = ApiUrl

/// 1 = Email address to query /// 2 = API Key

/// </summary>

private const string QueryFormatString = @"{0}?email={1}&key={2}"; /// <summary>

/// The your api key. /// </summary>

/// <remarks>

/// /*ENTER YOUR API KEY HERE*/ /// </remarks>

private const string YourAPIKey = @"";

#endregion

#region Methods

/// <summary>

/// The main program entry point. /// </summary>

/// <param name="args"> /// The args.

/// </param>

private static void Main(string[] args) {

Console.WriteLine("Input email address to verify");

var readLine = Console.ReadLine();

(37)

var myRequest = (HttpWebRequest)WebRequest.Create(requestUrl); WebResponse webResponse = null;

try {

webResponse = myRequest.GetResponse();

using (var reader = new StreamReader(webResponse.GetResponseStream())) {

var jsonString = reader.ReadToEnd();

Console.ForegroundColor = ConsoleColor.Green; Console.WriteLine("Result:");

Console.WriteLine(jsonString); Console.ResetColor();

Console.WriteLine("Press <Enter> to continue.."); Console.ReadLine();

} }

catch (Exception exception) {

Console.WriteLine("An error occured:"); Console.ForegroundColor = ConsoleColor.Red;

Console.WriteLine("Exception reported: {0}", exception.Message); Console.ResetColor();

Console.WriteLine("Press <Enter> to continue.."); Console.ReadLine(); } finally { if (webResponse != null) { webResponse.Dispose(); } } } #endregion } VB.net Imports System.IO Imports System.Net ''' <summary> ''' The program. ''' </summary> Friend Class Program

(38)

''' <summary> ''' The api url. ''' </summary>

Private Const ApiUrl As String = "http://api1.27hub.com/api/a/v1" ''' <summary>

''' 0 = ApiUrl

''' 1 = Email address to query ''' 2 = API Key

''' </summary>

Private Const QueryFormatString As String = "{0}?email={1}&key={2}" ''' <summary>

''' The your api key. ''' </summary>

''' <remarks>

''' /*ENTER YOUR API KEY HERE*/ ''' </remarks>

Private Const YourAPIKey As String = ""

#End Region

#Region "Methods"

''' <summary>

''' The main program entry point. ''' </summary>

''' <param name="args"> ''' The args.

''' </param>

Private Shared Sub Main(args As String())

Console.WriteLine("Input email address to verify")

Dim readLine = Console.ReadLine()

Console.WriteLine(String.Empty)

Dim requestUrl = String.Format(QueryFormatString, ApiUrl, readLine, YourAPIKey) Dim myRequest = DirectCast(WebRequest.Create(requestUrl), HttpWebRequest)

Dim webResponse As WebResponse = Nothing Try

webResponse = myRequest.GetResponse()

Using reader = New StreamReader(webResponse.GetResponseStream()) Dim jsonString = reader.ReadToEnd()

Console.ForegroundColor = ConsoleColor.Green Console.WriteLine("Result:")

Console.WriteLine(jsonString) Console.ResetColor()

Console.WriteLine("Press <Enter> to continue..") Console.ReadLine()

End Using

Catch exception As Exception

(39)

Console.WriteLine("Press <Enter> to continue..") Console.ReadLine()

Finally

If webResponse IsNot Nothing Then webResponse.Dispose() End If End Try End Sub #End Region End Class Java /* ******************************************************************************************* * Company: * (c) 2016, email-checker.com (https://www.emailhippo.com) * * File name: * java.v1_key_acl * * Version: * 1.0.20140827.0 * * Version control: * - 1.0.20140827.0 - initial release * * Date: * August 2014 * * Description:

* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/a/v1 * using java.

*

* This example requires a valid key to work correctly. * * License: * Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0) ******************************************************************************************* */ import java.io.BufferedReader; import java.io.IOException; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import java.util.Scanner; import java.util.logging.Level; import java.util.logging.Logger;

(40)

/*

* The URL which should be requested */

private static final String ApiUrl = "http://api1.27hub.com/api/a/v1";

/*

* Query string for request * %1$s = ApiUrl

* %2$s = Email address to query * %3$s = API Key

*/

private static final String QueryFormatString = "%1$s?email=%2$s&key=%3$s";

/*

* Your API Key *

*/

private static final String YourAPIKey = _{"/* ENTER A VALID KEY HERE */"}; /**

* The main program entry point

* @param args the command line arguments

* @throws IOException If the server does not return a success response */

public static void main(String[] args) {

System.out.println("Input email address to verify");

// Create a scanner to read in the requested email address Scanner in = new Scanner(System.in);

String readLine = in.next();

try {

// Format the request url to the correct structure for the request

URL requestUrl = new URL(String.format(QueryFormatString, ApiUrl, readLine, YourAPIKey));

// Open a connection to the website

HttpURLConnection myRequest = (HttpURLConnection) requestUrl.openConnection();

// Set the type to HTTP GET

myRequest.setRequestMethod("GET");

// Create a new buffered reader to read the response back from the server BufferedReader reader = new BufferedReader(

new InputStreamReader(myRequest.getInputStream()));

String inputLine;

StringBuilder response = new StringBuilder();

// Read in the response line from the server while ((inputLine = reader.readLine()) !=null ) {

response.append(inputLine); }

// Close the reader reader.close();

(41)

{

Logger.getLogger(Program.class.getName()).log(Level.SEVERE, null, ex); } } } Python ########################################################################################### # Company: # (c) 2016, emailhippo.com (https://www.emailhippo.com) # # Version: # 1.0.20140827.0 # # Version control: # - 1.0.20140827.0 - initial release # # Date: # August 2014 # # Description:

# Demonstrates how to call a RESTful service @ //api1.27hub.com/api/a/v1 # using Python

#

# This example requires a valid key to work correctly. #

# License:

# Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)

###########################################################################################

# Import the module for handling the http request import urllib.request

# The url for the service

ApiUrl = "http://api1.27hub.com/api/a/v1"

# The format of the full query string QueryFormatString = "{0}?email={1}&key={2}"

# The API key provided for your account goes here YourAPIKey = ""

# Read in the user input

readLine = input("Enter Email:\n")

# Format the full url and make the http GET request and read the response

response = urllib.request.urlopen(QueryFormatString.format(ApiUrl, readLine, YourAPIKey)).read()

(42)

Real Time Email Verification API Documentation, Release 1.0.17 PERL ########################################################################################### # Company: # (c) 2016, emailhippo.com (https://www.emailhippo.com) # # File name: # Program.pl # # Version: # 1.0.20140828.0 # # Version control: # - 1.0.20140828.0 - initial release # # Date: # August 2014 # # Description:

# Demonstrates how to call a RESTful service @ //api.27hub.com/api/a/v1 # using Perl using client side only calls.

#

# This example requires a valid key to work correctly. #

# License:

# Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)

########################################################################################### use LWP;

# The url for the service

$ApiUrl = "http://api1.27hub.com/api/a/v1"; # The format of the full query string $QueryFormatString = "%s?email=%s&key=%s";

print "Enter Email:\n"; $readLine = <STDIN>;

# The API key provided for your account goes here $YourAPIKey = ""; # Format the url request

$requestUrl = sprintf $QueryFormatString, $ApiUrl, $readLine, $YourAPIKey;

# Make the request against the REST service $browser = LWP::UserAgent->new;

$response = $browser->get($requestUrl); # Print the response

print $response->content;

11.1.2 Client Examples

jQuery (domain ACL)

(43)

<!--******************************************************************************************* * Company: * (c) 2016, emailhippo.com (https://www.emailhippo.com) * * File name: * v1_domain_acl.html * * Version: * 1.0.20140827.0 * * Version control: * - 1.0.20140827.0 - initial release * * Date: * August 2014 * * Description:

* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/a/v1 * using jQuery, client side only calls.

*

* This example requires a domain ACL and hosting at specified domain to work correctly. * * License: * Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0) ******************************************************************************************* --> <html lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <meta charset="utf-8" />

<title>emailhippo.com : Domain Access Control List Sample.</title> <style type="text/css">

.statusUnknown{ color: #c1c72c;}

.statusOk{ color: #009933;}

.statusBad,.errorMsg{ color: #ff0000;}

input[type='text']{ width: 300px;}

p label {display: inline-block; width: 60px;}

</style>

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> </head>

<body>

<h1>emailhippo.com : email verification demo using domain access control list authentication with jQuery.</h1> <h2>About</h2>

<p>This example shows how to perform email verification using just client side scripting and invoking a domain based <abbr title="Access Control List">ACL</abbr> RESTful endpoint at <a href="https://api1.27hub.com" target="_blank">api1.27hub.com</a>.</p> <h2>How to run this sample</h2>

<p>Two things are needed to run this sample:</p> <ol>

<li>A domain <abbr title="Access Control List">ACL</abbr> is required from your email verification API provider. Domain ACLs are applied against a domain of your choosing (e.g. www.yourdomain.com).</li> <li>Web hosting for www.yourdomain.com.</li>

</ol>

(44)

<li>Compatible with all modern browsers</li> <li>Uses jQuery 1.11.1</li>

<li>No server side scripting required</li> </ul>

<hr/>

<h2>Try it</h2> <p>

<label for="email">Email:</label>

<input type="text" name="email" id="email" />

<input type="button" name="submit" id="submit" value="verify"/> </p>

<div id="validationResult"></div>

<script>

/*nest key logic inside document.ready to ensure functionality only available once document has fully loaded in browser.*/ $(function () {

console.log("ready!");

$('#submit').click(function () {

var emailText = $('#email').val(); if (emailText.length == 0) {

$('#validationResult').html("<span class='errorMsg'>Please enter something.</span>"); return;

}

$('#validationResult').html("verifying...");

var emailVerifyApi = '//api1.27hub.com/api/a/v1?email=' + encodeURIComponent(emailText);

/*execute remote request to perform email verification. Any errors will appear in the developer console (e.g. viewable using Chrome developer tools)*/ $.getJSON(emailVerifyApi, {})

.done(function (data) { reportResult(data); })

.fail(function (jqxhr, textStatus, error) { var err = textStatus + ", " + error; console.log("Request failed: " + err); });;

}); });

/*Output result to the 'validationResult' div element*/ function reportResult(data) {

var status = data['status'].toLowerCase(); // get 'status' from REST response

var additionalStatus = data['additionalStatus']; // get 'additionalStatus' from REST response

var message = data['Message']; // if there is an error (e.g. license issues), a notification will appear in the 'Message" from REST response.

console.log(status);

console.log(additionalStatus); console.log(message);

var statusHtml;

// if there is an error message, show here if (message != null

&& message != '') {

statusHtml = "<span class='errorMsg'>Error. Message='" + message + "' .</span>"; } else {

(45)

break; case 'bad':

statusHtml = "<span class='statusBad'>Email address is not valid.</span>"; break;

default:

statusHtml = "<span class='statusUnknown'>Unable to validate email. Reason=" + additionalStatus + "</span>"; break;

} }

console.log(statusHtml);

// present the result on screen

$('#validationResult').html(statusHtml); }

</script> </body>

</html>

jQuery (license key)

Note: Demonstrates how to call aRESTfulservice @ //api1.27hub.com/api/a/v1 using jQuery using client side only calls <!DOCTYPE html> <!--******************************************************************************************* * Company: * (c) 2016, www.emailhippo.com.com (https://www.emailhippo.com) * * File name: * v1_key_acl.html * * Version: * 1.0.20140827.0 * * Version control: * - 1.0.20140827.0 - initial release * * Date: * August 2014 * * Description:

* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/a/v1 * using jQuery using client side only calls.

*

* This example requires a valid key to work correctly. *

(46)

Real Time Email Verification API Documentation, Release 1.0.17 ******************************************************************************************* --> <html lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <meta charset="utf-8" />

<title>27hub.com : License Key Sample.</title> <style type="text/css"> .statusUnknown { color: #c1c72c; } .statusOk { color: #009933; } .statusBad, .errorMsg { color: #ff0000; }

input[type='text'] { width: 300px; }

p label {

display: inline-block; width: 60px; }

</style>

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script> </head>

<body>

<h1>27hub.com : email verification demo using simple key authentication with jQuery.</h1> <h2>About</h2>

<p>This example shows how to perform email verification using just client side scripting and invoking a simple key based RESTful endpoint at <a href="https://api.27hub.com" target="_blank">api.27hub.com</a>.</p> <h2>How to run this sample</h2>

<p>This page can be hosted anywhere (i.e. any web host or platform). The only thing needed is a valid license key.</p> <h2>Key features</h2>

<ul>

<li>Compatible with all modern browsers</li> <li>Uses jQuery 1.11.1</li>

<hr />

<h2>Try it</h2> <p>

<label for="key">Key:</label>

<input type="text" id="key" name="key" tabindex="1" maxlength="20" /> </p>

<p>

<input type="text" name="email" id="email" tabindex="2" />

<input type="button" name="submit" id="submit" tabindex="3" value="verify" /> </p>

<div id="validationResult"></div>

<script>

/*nest key logic inside document.ready to ensure functionality only available once document has fully loaded in browser.*/ $(function () {

console.log("ready!");

$('#submit').click(function () {

(47)

$('#validationResult').html("<span class='errorMsg'>Please enter key.</span>"); return;

}

if (emailText.length == 0) {

$('#validationResult').html("<span class='errorMsg'>Please enter something for email.</span>"); return;

}

$('#validationResult').html("verifying...");

var 27hub = '//api1.27hub.com/api/a/v1?email=' + encodeURIComponent(emailText) + '&key=' + keyText;

/*execute remote request to perform email verification. Any errors will appear in the developer console (e.g. viewable using Chrome developer tools)*/ $.getJSON(27hub, {})

.done(function (data) { reportResult(data); })

.fail(function (jqxhr, textStatus, error) { var err = textStatus + ", " + error; console.log("Request failed: " + err); });;

}); });

/*Output result to the 'validationResult' div element*/ function reportResult(data) {

var status = data['status'].toLowerCase(); // get 'status' from REST response

var additionalStatus = data['additionalStatus']; // get 'additionalStatus' from REST response

var message = data['Message']; // if there is an error (e.g. license issues), a notification will appear in the 'Message" from REST response.

var statusHtml;

&& message != '') {

statusHtml = "<span class='errorMsg'>Error. Message='" + message + "' .</span>"; } else {

// map REST response data to presentation messages. switch (status) {

case 'ok':

statusHtml = "<span class='statusOk'>Email address is ok.</span>"; break;

case 'bad':

statusHtml = "<span class='statusBad'>Email address is not valid.</span>"; break;

default:

statusHtml = "<span class='statusUnknown'>Unable to validate email. Reason=" + additionalStatus + "</span>"; break;

(48)

}

console.log(statusHtml);

// present the result on screen

$('#validationResult').html(statusHtml); }

</script> </body>

</html>

AngularJS (license key)

Note: Demonstrates how to call aRESTfulservice @ //api1.27hub.com/api/a/v1 using AngularJS with client side only calls. <!DOCTYPE html> <!--******************************************************************************************* * Company: * (c) 2016, emailhippo.com (https://www.emailhippo.com) * * File name: * v1_key_acl.html * * Version: * 1.0.20140827.0 * * Version control: * - 1.0.20140827.0 - initial release * * Date: * August 2014 * * Description:

* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/a/v1 * using AngularJS with client side only calls.

*

* This example requires a valid key to work correctly. * * License: * Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0) ******************************************************************************************* --> <html lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <meta charset="utf-8" />

<title>emailhippo.com : License Key Sample.</title> <style type="text/css">

.statusUnknown {

color: #c1c72c; }

.statusOk {

(49)

}

input[type='text'],input[type='email'] { width: 300px; } p label { display: inline-block; width: 60px; } </style> </head> <body>

<h1>emailhippo.com : email verification demo using simple key authentication with AngularJS.</h1> <h2>About</h2>

<p>This example shows how to perform email verification using just client side scripting and invoking a simple key based RESTful endpoint at <a href="https://api1.27hub.com" target="_blank">api1.27hub.com</a>.</p> <h2>How to run this sample</h2>

<p>This page can be hosted anywhere (i.e. any web host or platform). The only thing needed is a valid license key.</p> <h2>Key features</h2>

<ul>

<li>Compatible with all modern browsers</li> <li>Uses AngularJS 1.2.23</li>

<hr />

<h2>Try it</h2>

<div id="MyApp" ng-app="apiDemo" ng-controller="apiDemoController"> <form name="verifyForm" novalidate="" ng-submit="doVerify()">

<p>

<label for="key">Key:</label>

<input type="text" id="key" name="key" tabindex="1" maxlength="20" ng-model="query.key" required="" /> <span class="errorMsg" ng-show="verifyForm.key.$error.required">*</span>

</p> <p>

<input type="email" name="email" id="email" tabindex="2" ng-model="query.email" required="" /> <span class="errorMsg" ng-show="verifyForm.email.$error.required">*</span>

<span class="errorMsg" ng-show="verifyForm.email.$error.email">not valid email</span> </p>

<p>

<label> </label>

<input type="submit" name="submit" id="submit" tabindex="3" value="verify" /> </p>

</form>

<div id="validationResult">

<div ng-show="showValidating">verifying..</div>

<div ng-show="showOk"><span class="statusOk">Email address is ok.</span></div>

<div ng-show="showBad"><span class="statusBad">Email address is not valid.</span></div>

<div ng-show="showUnknown"><span class="statusUnknown">Unable to validate email. Reason={{additionalStatusMessage}}</span></div> <div ng-show="showMessage"><span class="errorMsg">Error. Message={{errorMessage}}</span></div>

</div> </div>

(50)

<script>

// Module

var app = angular.module('apiDemo', []);

// Controller

app.controller('apiDemoController', function apiDemoController($scope,$http) { $scope.query = { key: "", email: "" }; $scope.result = { status: "", additionalStatus: "" }; // verification event $scope.doVerify = function () { resetMessage(); $scope.showValidating = true;

var emailVerifyApi = '//api1.27hub.com/api/a/v1?email=' + encodeURIComponent($scope.query.email) + '&key=' + $scope.query.key; console.log(emailVerifyApi);

$http.get(emailVerifyApi)

.success(function (response) { resetMessage();

var status = response['status'].toLowerCase(); var additionalStatus = response['additionalStatus']; var message = response['Message'];

&& message != '') {

$scope.errorMessage = message; $scope.showMessage = true;

} else {

// map REST response data to presentation messages. switch (status) { case 'ok': $scope.showOk = true; break; case 'bad': $scope.showBad = true; break; default: $scope.additionalStatusMessage = additionalStatus; $scope.showUnknown = true; break; } } });

(51)

$scope.showMessage = false; $scope.showOk = false; $scope.showUnknown = false; $scope.showMessage = false; } } }); </script> </body> </html> CURL ******************************************************************************************* * Company: * © 2016, emailhippo.com (https://www.emailhippo.com) * * File name: * cURL.txt * * Version: * 1.0.20140828.0 * * Version control: * - 1.0.20140828.0 - initial release * * Date: * August 2014 * * Description:

* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/a/v1 * using cURL

*

* This example requires a valid key to work correctly. *

* License:

* Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)

*******************************************************************************************

(52)

(53)

Glossary

12.1 Glossary

ACL Access Control List.

An ACL is checked against the domain calling theAPI. ACL authentication does not require a license key and is best in situations where theAPIis being called from client side script such as JavaScript, jQuery, Angular etc. API Application Programmers Interface.

SeeWikipedia - API Definitionfor more information. B2B Business To(2) Business

Business email hosting services are generally private, enterprise grade hosting services typically hosted in either private data centers or in cloud based infrastructure such.

Business to business refers to the activity of businesses sending email to clients using business email addresses. B2C Business To(2) Consumer

Consumer email hosting providers are generally well known, mostly web based providers such as Hotmail, Yahoo, AOL, Gmail etc.

Business to consumer refers to the activity of businesses sending email to clients using consumer email ad-dresses.

Verifying email addresses in consumer domains is generally more technically challenging thanB2B Block List SeeDNSBL.

CORS Cross Origin Resource Scripting

Allows modern browsers to work with script (e.g. JavaScript) andJSONdata originating form other domains. CORS is required to allow client script such a JavaScript, jQuery or AngularJS to work with results returned from an externalRESTful API.

SeeWikipedia - CORSfor more information. DDoS Distributed Denial of Service

SeeWikipedia - Denial-of-service attackfor more information. DEA Disposable Email Address

(54)

DEA addresses should not be regarded as valid for email send purposes as it is unlikely that messages sent to DEA addresses will ever be read. DEA addresses should not be regarded as valid for email send purposes as it is unlikely that messages sent to DEA addresses will ever be read.

DNS Domain Name System

At its simplest level, DNS converts text based queries (e.g. a domain name) into IP addresses. DNS is also responsible for providing theMXrecords needed to locate a domains mail servers. SeeWikipedia - Domain Name Systemfor more information.

DNSBL DNS Block List

As an anti-spam measure, mail servers can use spam black lists to ‘look up’ the reputation of IP addresses and domains sending email. If an IP or domain is on a block list, the mail server may reject the senders email message.

SeeWikipedia - DNSBLfor more information. ESP Email Service Provider

A service that sends emails on your behalf.

SeeWikipedia - Email service provider (marketing)for more information.

Grey Listing A technique used in mail servers as an anti-spam technique. Sometimes also known as “deferred”, grey listing arbitrarily delays the delivery of emails with a “try again later” response to the client sending the email. SeeWikipedia - Grey Listingfor more information.

HTTP Hypertext Transfer Protocol

SeeWikipedia - Hypertext Transfer Protocolfor more information. JSON JavaScript Object Notation

JavaScript Object Notation, is an open standard format that uses human readable text to transmit data objects consisting of attribute value pairs. It is used primarily to transmit data between a server and web application, as an efficient, modern alternative to XML.

SeeWikipedia - JSONfor more information.

License Key License key authentication is best for situations where simplicity is required and you can keep the key private. An ideal use case for key authentication would be for server based applications calling the RESTful API.

Click hereto request a license key. MX Mail Exchanger

The MX is a server responsible for email interchange with a client.

Office 365 Office 365 mail servers (e.g. x-com.mail.protection.outlook.com) are always configured with the catch all policy, accepting all emails sent to the domain and redirecting them to a central email box for manual inspection. Catch all configured servers cannot respond to requests for email address verification.

This does not affect our coverage of Hotmail, Live and Outlook mail boxes.

Punycode Punycode is a way to represent Unicode with the limited character subset of ASCII supported by the Domain Name System.

SeeWikipedia - Punycodefor more information. RESTful Representational state transfer

SeeWikipedia - RESTfulfor further information.

(55)

Spam Trap Spam traps are email addresses used for the sole purpose of detecting spamming activities. Spam traps are used by many block lists (DNSBL) to detect spammers.

(56)

(57)

A

ACL,49 API,49

B

B2B,49 B2C,49 Block List,49

C

CORS,49

D

DDoS,49 DEA,49 DNS,50 DNSBL,50

E

ESP,50

G

Grey Listing,50

H

HTTP,50

J

JSON,50

L

License Key,50

M

MX,50

O

Office 365,50

P

Punycode,50

R

RESTful,50

S

SMTP,51 Spam Trap,51