Technical Overview

Technical features
  • Progressive verification using multiple verification processes including:

    • Syntax checking
    • DNS checking
    • Block-list checking (e.g. spamhaus)
    • Web infrastructure checking
    • Mailbox checking

  • Unrivalled coverage - Email Hippo leverages the advantages of its scalable infrastructure to provide coverage of domains that are technically challenging. Consumer facing domains tend to be more challenging to cover then business facing domains B2C domains including:

    • Hotmail
    • Yahoo
    • Office 365
    • AOL
    • Yandex
  • Spam trap detection - Email Hippo has developed technology that can effectively identify any probable Spam Trap.

  • Disposable email address detection - Unrivalled disposable email address detection built on Email Hippo’s proprietary multi-vector real-time analysis:

    • Real-time detection of disposable email address providers that employ obfuscation techniques (e.g. rotating domains, IP addresses and MX servers)
    • Checking against static lists

  • Returns:
    • Primary and secondary results codes
    • Role, free and disposable identifiers
    • Mail server location

  • Thoughtful versioning - Endpoints are ‘versioned’ allowing the release of new functionality without forcing customers to change or break if they are committed to integrating with legacy endpoints.
Technical specification

 

Item Specification
Manufacturer emailhippo.com
Current version v2
Uptime > 99.99%
Response time >0.2 seconds < 8 seconds. Typical response time 0.4 seconds. 
Maximum wait time 90 seconds. This is the maximum time we'll wait for email servers to respond.
Throughput and concurrency 220 TPS(Transactions Per Second)
Security and encryption Transport security using HTTPS. Data at rest encrypted using 256-bit AES encryption.
Integration RESTful GET over HTTPS, XML GET over HTTPS, BSON over HTTPS, protobuf over HTTPS
Authentication License key
Infrastructure Dispersed cloud data centers, auto load balance / failover.

 

Concurrency

To preserve the operational integrity of the service to all of our customers, there is a maximum concurrency enforced by our systems.

Limits

Allowed throughput is 220 MORE email validation requests per second.

Throughput exceeding these limits will receive HTTP response code 429 (too many requests) for subsequent requests for a duration of one minute.

Suggestions on how to manage throughput

If you experience or anticipate exceeding throughput limits, here are two ways to control query rates:

  • Test your integration with representative production loads over a period of time. Monitor response codes for any 429’s. If you see any 429’s please reduce the rate at which your application is querying our servers.

  • For applications that can tolerate slight delays in your data processing mesh, consider using queuing infrastructure with a rate controllable processor. Your ‘processor’ can then schedule picking work off the queue and submitting requests to our systems at a controllable rate.

Large throughput requirement

For sustained throughput of more than 220 queries per second, please contact us.


Authentication

Email Hippo MORE uses API keys to allow access to the API.

Email Hippo MORE expects the API key to be included in all API requests to the server.

{k}: yourlicensekey

 You must replace yourlicensekey with your personal API key.


Endpoint request

Performs email address verification.

GET //api1.27hub.com/api/emh/a/v2?k={k}&e={e}

GET email verification result.

Parameter In Type Required Description
k path string true the license key
e path string true the email address to validate

 

Responses (including errors)
Status Meaning Description Schema
200 OK Success ResultRecord
400 Bad Request 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. None
401 Unauthorised Possible reasons: The provided license key is not valid, the provided license key has expired, you have reached your quota capacity for this account, this account has been disabled. None
429 Too many requests Maximum processing rate exceeded. See Concurrency for further information. None
500 Internal Server Error An error occurred on the server. Possible reasons are: license key validation failed or a general server fault. None
JSON response

{
"result": "string",
"reason": "string",
"role": true,
"free": true,
"disposable": true,
"email": "string",
"domain": "string",
"user": "string",
"mailServerLocation": "string",
"duration": 0
}

Result record schema
Name Type Required Restrictions Description
result string false none Primary result codes
reason string false none Secondary reason codes
role boolean false none Is a role address? (e.g. info@, sales@, postmaster@)
free boolean false none Is a free mail provider? (e.g. gmail, hotmail etc)
disposable boolean false none Is a disposable email address (DEA)?
email string false none The email being queried
domain string false none The domain of the email being queried
user string false none The user element of the email address
mailServerLocation string false none Mail server location as a 2 digit ISO code (e.g. US)
duration integer false none The elapsed time (ms) to execute the query
Result codes

 

Primary result codes

Primary code Description
Ok Verification passes all checks including Syntax, DNS, MX, Mailbox, Deep server configuration, Greylisting.
Bad Verification fails checks for definitive reasons (e.g. mailbox does not exist).
Unverifiable Conclusive verification result cannot be achieved due to mail server configuration or anti-spam measures.
RetryLater Conclusive verification result cannot be achieved at this time. Please try again later. - This is ShutDowns, IPBlock, TimeOuts.

 

Secondary reason codes

Primary code Secondary reason Description
Ok Success Successful verification. 100% confidence that the mailbox exists.
Bad AtSignNotFound The required ‘@’ sign is not found in email address.
Bad DomainIsInexistent The domain (i.e. the bit after the ‘@’ character) defined in the email address does not exist, according to DNS records. A domain that does not exist cannot have email boxes.
Bad 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.
Bad MailboxDoesNotExist The mailbox does not exist. 100% confidence that the mail box does not exist.
Bad NoMxServersFound There are no mail servers defined for this domain, according to DNS. Email addresses cannot be valid if there are no email servers defined in DNS for the domain.
Bad 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 for Punycode translation. Where these systems are not in place, email verification or delivery is not possible.
Bad TooManyAtSignsFound Too many ‘@’ signs found in email address. Only one ‘@’ character is allowed in email addresses.
Bad 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 your ESP being subjected to email blocks from a DNS Block List. An ESP cannot tolerate entries in a Block List (as it adversely affects email deliverability for all customers) and will actively refuse to send emails on behalf of customers with a history of generating entries in a Block List.
RetryLater 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. These conditions are usually temporary. Retrying verification at a later time will usually result in a positive response from mail servers. Please note that setting an infinite retry policy around this status code is inadvisable as there is no way of knowing when the issue will be resolved within the target domain or the grey listing resolved, and this may affect your daily quota.
Unverifiable 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 a mail provider implementing custom mailbox shutdowns.
Unverifiable DomainIsWellKnownDea The domain is a well known Disposable Email Address (DEA). 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). 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.
Unverifiable GreyListing Greylisting is in operation. It is not possible to validate email boxes in real-time where greylisting is in operation.
Unverifiable 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.
Unverifiable Unknown The reason for the verification result is unknown.

.Net client libraries

Pre-requisites and the package

We have a .NET package built for easy integration with our MORE Edition 1 (v2) API services.

If you're working in the .NET environment, this package can save you hours of work writing your own JSON parsers, message pumping logic, threading and logging code.

Prerequisites
  • Visual Studio 2017 or later
  • .NET Standard 2.0 or later
  • API license key
How to get the package

The package is available from Nuget.

Example custom code snippets

          
/* © 2017, Email Hippo Limited. (http://emailhippo.com)
*
* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
* This example requires a valid key to work correctly.
*
* License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
*/

curl -i -H "Accept: application/json" "//api1.27hub.com/api/emh/a/v2?k={YOUR_API_KEY}&e={EMAIL_ADDRESS}"
          
/*
* © 2017, Email Hippo Limited. (http://emailhippo.com)
*
* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
* This example requires a valid key to work correctly.
*
* License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
*/
<?php

// URL which should be requested
$url = 'https: @ //api1.27hub.com/api/emh/a/v2';

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

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

// jSON String for request
$url .= "?k={$apikey}&e={$email}";

// 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
$result = curl_exec($ch); // Getting jSON result string

// display JSON data
echo "$result";

}

?>
          
 /*
* © 2017, Email Hippo Limited. (http://emailhippo.com)
*
* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
* This example requires a valid key to work correctly.
*
* License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
*/

const request = require('node-fetch');

const headers = {
'Accept':'application/json'

};

fetch('//api1.27hub.com/api/emh/a/v2?k={k}&e={e}',
{
method: 'GET',

headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
 
          
 /*
* © 2017, Email Hippo Limited. (http://emailhippo.com)
*
* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
* This example requires a valid key to work correctly.
*
* License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
*/


URL obj = new URL("//api1.27hub.com/api/emh/a/v2?k={k}&e={e}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
          
# © 2017, Email Hippo Limited. (http://emailhippo.com)
#
# Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
# This example requires a valid key to work correctly.
#
# License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)

require 'rest-client'
require 'json'

headers = {
'Accept' => 'application/json'
}

result = RestClient.get '//api1.27hub.com/api/emh/a/v2?k={k}&e={e}',
params: {
}, headers: headers

p JSON.parse(result)
          
# © 2017, Email Hippo Limited. (http://emailhippo.com)
#
# Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
# 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 = "https://api1.27hub.com/api/emh/a/v2"

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

# The API key provided for your account goes here
YourAPIKey = "<!-- ENTER A VALID KEY HERE-->"

# 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, YourAPIKey, readLine)).read()

# Print the response
print(response)
          
 /*
* © 2017, Email Hippo Limited. (http://emailhippo.com)
*
* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
* This example requires a valid key to work correctly.
*
* License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
*/
package main

import (
"bytes"
"net/http"
)

func main() {

headers := map[string][]string{
"Accept": []string{"application/json"},

}

data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "//api1.27hub.com/api/emh/a/v2?k={k}&e={e}", data)
req.Header = headers

client := &http.Client{}
resp, err := client.Do(req)
// ...
}
          
/*
* © 2017, Email Hippo Limited. (http://emailhippo.com)
*
* Demonstrates how to call a RESTful service @ //api1.27hub.com/api/emh/a/v2
* This example requires a valid key to work correctly.
*
* License: Apache 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
*/


#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 = @"https:@ //api1.27hub.com/api/emh/a/v2";
/// <summary>
/// 0 = ApiUrl
/// 1 = API Key
/// 2 = Email address to query
/// </summary>
private const string QueryFormatString = @"{0}?k=1&e=2";

/// <summary>
/// The your api key.
/// </summary>
/// <remarks>
/// /*ENTER YOUR API KEY HERE*/
/// </remarks>
private const string YourAPIKey = @"<!-- ENTER A VALID KEY HERE-->";

#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();

Console.WriteLine(string.Empty);

var requestUrl = string.Format(QueryFormatString, ApiUrl, YourAPIKey, readLine);

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
}

Talk to us about your integration requirements

If you'd like more information about a popular Email Hippo integration, or would like to discuss an integration requirement,  or  if you just have an integration question please get in touch today and we'll help you find the best solution for you.

Not yet using Email Hippo for your email verification?

What are you waiting for?

Trial our email verification for freeRegister today for 100 free email validations. No credit card details needed to create your account.