NAV
JSON Shell PHP Node.JS Java Ruby Python Go C# .Net

Email Hippo Technical Documentation

Introduction

Welcome to the home of Email Hippo technical documents. From here you can access full information about all our APIs, view code in multiple languages and get started with your own integration.

About Email Hippo

Email Hippo is an email intelligence and data services provider that’s trusted by thousands of businesses and holds international security accreditations.

We deliver accurate cloud-based email validation and domain profiling. API use cases include data cleansing on demand or in real-time, fraud prevention and user signposting scenarios to improve user experience and build effective communication processes.

Our monitoring and detection of disposable email addresses is unrivalled.

Email Hippo website

About our APIs

> 99.99% uptime

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

Easy integration

Take a look at our enpoints and code samples to see how quick and easy it is to integrate with our services.

Fast, transparent response times

Every query response includes stopwatch data that shows the time taken to execute the request. Typical queries are answered in under 0.5 seconds.

Unrivalled performance

Strategic data centers in Europe, aggressive caching, global network delivery optimization and cloud-based auto-scaling deliver outstanding performance.

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.

Service Status

For information on the status and performance of our services visit status.emailhippo.com.

Service Status Page

MORE email validation API

MORE is our email validation API. It's availble in two versions:

Edition 1 - the fastest, slimmed down version known as V2 uses our comprehensive email validation engine and returns essential result information. Results do not include the Email Hippo Trust Score.

Edition 2 - the comprehensive, feature rich version known as V3 uses the same comprehensive email validation engine and returns 74 data points including the Email Hippo Trust Score.

Common features shared by both Editions:

Edition 2 features:

What is the risk of sending an email to the email address that’s being validated?

MORE Edition 1 - V2

Specification

Item Spec
Manufacturer emailhippo.com
Current version v2
Uptime > 99.99%
Response time >0.2 seconds < 8 seconds. Typical response time 0.4 seconds.
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
Authentication License key
Infrastructure Geographically 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:

Large throughput requirement

For sustained throughput of more than 50 domain queries per second, please contact us about a private, dedicated service.

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

Endpoint - GET email address verification 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)

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)
*/

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

Performs email address verification.

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

GET email verification result.

Parameters

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

Result record schema

{
"result": "string",
"reason": "string",
"role": true,
"free": true,
"disposable": true,
"email": "string",
"domain": "string",
"user": "string",
"mailServerLocation": "string",
"duration": 0
}
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. [email protected], [email protected], [email protected])
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

We have a .NET package built for easy integration with our MORE Edition 1 (v2) API services. For further information on the RESTful server side implementation, please see the docs and schema.

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.

How to get the package

The package is available from Nuget.

MORE Edition 2 - V3

Specification

Item Spec
Manufacturer emailhippo.com
Current version v3
Uptime > 99.99%
Response time >0.2 seconds < 8 seconds. Typical response time 0.4 seconds.
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 Geographically 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:

Large throughput requirement

For sustained throughput of more than 220 email validations per second, please contact us about a private, dedicated service.

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

Endpoint - GET quota usage

# © 2017, Email Hippo Limited. (http://emailhippo.com)
#
# Demonstrates how to call a RESTful service @ //api.hippoapi.com/customer/reports/v3/quota
# 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://api.hippoapi.com/customer/reports/v3/quota"

# The format  of the full query string
QueryFormatString = "{0}/{1}"

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

# Format the full url and make the http GET request and read the response
response = urllib.request.urlopen(QueryFormatString.format(ApiUrl, YourAPIKey)).read()

# Print the response
print(response)
* © 2017, Email Hippo Limited. (http://emailhippo.com)
 *
 * Demonstrates how to call a RESTful service @ //api.hippoapi.com/customer/reports/v3/quota
 * 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" "https://api.hippoapi.com/customer/reports/v3/quota/YOUR_API_KEY"
/*
 * © 2017, Email Hippo Limited. (http://emailhippo.com)
 *
 * Demonstrates how to call a RESTful service @ //api.hippoapi.com/customer/reports/v3/quota
 * 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://api.hippoapi.com/customer/reports/v3/quota';

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



// jSON String for request
$url .= "/$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
  $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 @ //api.hippoapi.com/customer/reports/v3/quota
 * 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://api.hippoapi.com/customer/reports/v3/quota";
    /// <summary>
    /// 0 = ApiUrl
    /// 1 = API Key
    /// </summary>
    private const string QueryFormatString = @"{0}/{1}";

    /// <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)
    {
        var requestUrl = string.Format(QueryFormatString, ApiUrl, YourAPIKey);

        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
}
const request = require('node-fetch');

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

};

fetch('//api.hippoapi.com/customer/reports/v3/quota/{k}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});
URL obj = new URL("//api.hippoapi.com/customer/reports/v3/quota/{k}");
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());
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", "//api.hippoapi.com/customer/reports/v3/quota/{k}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}
require 'rest-client'
require 'json'

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

result = RestClient.get '//api.hippoapi.com/customer/reports/v3/quota/{k}',
  params: {
  }, headers: headers

p JSON.parse(result)

Retrieves the current usage details for a given license key.

GET //api.hippoapi.com/customer/reports/v3/quota/{k}

GET QUOTA record.

Parameters

Parameter In Type Required Description
k path string true the license key

Responses (including errors)

Status Meaning Description Schema
200 OK Success QuotaRecord
400 Bad Request Must enter a valid license key to query or invalid format. None
404 Not Found No data found. None
422 Unprocessable Entity Cannot process a fully parsed respone. Top Level Domain (TLD) is not supported. None
500 Internal Server Error Server error. None

QuotaRecord schema

{
  "accountId": 0,
  "licenseKey":"string", 
  "quotaUsed": 0,
  "quotaRemaining": 0,
  "nextQuotaResetDate": "2018-08-09T10:26:42Z",
  "reportedDate": "2018-08-09T10:26:42Z",
  "errorSummary": "string"  
}
Name Type Required Restrictions Description
accountId integer(int32) false none none
licenseKey string false none none
quotaUsed integer(int64) false none none
quotaRemaining integer(int64) false none none
nextQuotaResetDate datetime false none none
reportedDate datetime false none none
errorSummary string false none none

Endpoint - GET email address verification result

# © 2017, Email Hippo Limited. (http://emailhippo.com)
#
# Demonstrates how to call a RESTful service @ //api.hippoapi.com/v3/more/json
# 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://api.hippoapi.com/v3/more/json"

# The format  of the full query string
QueryFormatString = "{0}/{1}/{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 @ //api.hippoapi.com/v3/more/json
 * 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" "https://api.hippoapi.com/v3/more/json/YOUR_API_KEY/EMAIL_ADDRESS"
/*
 * © 2017, Email Hippo Limited. (http://emailhippo.com)
 *
 * Demonstrates how to call a RESTful service @ //api.hippoapi.com/v3/more/json
 * 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://api.hippoapi.com/v3/more/json';

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

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

// jSON String for request
$url .= "/$apikey/$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 @ //api.hippoapi.com/v3/more/json
 * 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://api.hippoapi.com/v3/more/json";
    /// <summary>
    /// 0 = ApiUrl
    /// 1 = API Key
    /// 2 = Email address to query
    /// </summary>
    private const string QueryFormatString = @"{0}/{1}/{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
}
const request = require('node-fetch');

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

};

fetch('//api.hippoapi.com/v3/more/json/{k}/{e}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});
URL obj = new URL("//api.hippoapi.com/v3/more/json/{k}/{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());
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", "//api.hippoapi.com/v3/more/json/{k}/{e}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}
require 'rest-client'
require 'json'

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

result = RestClient.get '//api.hippoapi.com/v3/more/json/{k}/{e}',
  params: {
  }, headers: headers

p JSON.parse(result)

Performs email address verification to the full data enrichment level and returns the data in four formats:

GET email verification result.

Parameters

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

Result record schema

{
  "version": {
    "v": "string",
    "doc": "string"
  },
  "meta": {
    "lastModified": "string",
    "expires": "string",
    "email": "string",
    "tld": "string",
    "domain": "string",
    "subDomain": "string",
    "user": "string",
    "emailHashMd5": "string",
    "emailHashSha1": "string",
    "emailHashSha256": "string"
  },
  "disposition": {
    "isRole": true,
    "isFreeMail": true
  },
  "emailVerification": {
    "syntaxVerification": {
      "isSyntaxValid": true,
      "reason": "string"
    },
    "dnsVerification": {
      "isDomainHasDnsRecord": true,
      "isDomainHasMxRecords": true,
      "recordRoot": {
        "ipAddresses": [
          "string"
        ]
      },
      "recordWww": {
        "ipAddresses": [
          "string"
        ]
      },
      "mxRecords": [
        {
          "preference": 0,
          "exchange": "string",
          "ipAddresses": [
            "string"
          ]
        }
      ],
      "txtRecords": [
        "string"
      ]
    },
    "mailboxVerification": {
      "result": 0,
      "reason": 0
    }
  },
  "infrastructure": {
    "mail": {
      "serviceTypeId": "string",
      "mailServerLocation": "string",
      "smtpBanner": "string"
    }
  },
  "sendAssess": {
    "inboxQualityScore": 0,
    "sendRecommendation": "string"
  },
  "spamAssess": {
    "isDisposableEmailAddress": true,
    "isDarkWebEmailAddress": true,
    "isGibberishDomain": true,
    "isGibberishUser": true,
    "domainRiskScore": 0,
    "formatRiskScore": 0,
    "profanityRiskScore": 0,
    "overallRiskScore": 0,
    "actionRecomendation": "string",
    "blockLists": [
      {
        "blockListName": "string",
        "isListed": true,
        "listedReason": "string",
        "listedMoreInfo": "string"
      }
    ]
  },
  "spamTrapAssess": {
    "isSpamTrap": true,
    "spamTrapDescriptor": "string"
  },
  "hippoTrust": {
    "score": 0,
    "level": "string"
  },
  "social": {
    "gravatar": {
      "imageUrl": "string",
      "profileUrl": "string"
    }
  },
  "domain": "string",
  "performance": {
    "syntaxCheck": 0,
    "dnsLookup": 0,
    "spamAssessment": 0,
    "mailboxVerification": 0,
    "webInfrastructurePing": 0,
    "other": 0,
    "overallExecutionTime": 0
  },
  "diagnostic": {
    "key": "string"
  }
}
Name Type Required Restrictions Description Example use case
Version
 v string false none Contains details of the version and edition of API
 doc string false none
Meta
 lastModified string false none Last modified date/time of Email Hippo record
 expires string false none Date/time that this record expires from Email Hippo cache
 email string false none The email being queried
 tld string false none The Top Level Domain (TLD) of email being queried
 domain string false none The domain of the email being queried
 subDomain string false none The sub domain (if any) of the email being queried
 user string false none The user element of the email address
 emailHashMd5 string false none MD5 hash of the email address
 emailHashSha1 string false none SHA1 hash of the email address
 emailHashSha256 string false none SHA265 hash of the email address
Disposition
 isRole boolean false none Is a role address? (e.g. [email protected], [email protected], [email protected]) Request an additional contact email address
 isFreemail boolean false none Is a free mail provider? (e.g. gmail, hotmail etc) Exclude free email addresses in a Business to Business environment
EmailVerification
 syntaxVerification
  isSyntaxValid boolean false none Is the syntax of the email address correct according to RFC standards? Prompt your user that the email address has not been entered correctly
  reason string false none Syntax verification reason codes
 dnsVerification
  isDomainHasDnsRecord boolean false none Does the domain have any DNS records?
  isDomainHasMxRecords boolean false none Does the domain have any MX records?
  recordRoot
   ipAddresses string[] false none Details of root A record for domain
  recordWww
   ipAddresses string[] false none Details of records for WWW subdomain
  mxRecords mxRecord[] false none All MX records for domain
  txtRecords string[] false none All TXT records for domain
 mailboxVerification
  result string false none Primary result codes Act on results
  reason string false none Secondary reason codes Filter on reasons to maintain data quality
Infrastructure
 mail
  serviceTypeId string false none Service Type Identifier (e.g. Hotmail)
  mailServerLocation string false none Mail server location as a 2 digit ISO code (e.g. US) Analyse patterns of email systems
  smtpBanner string false none SMTP banner received on connect to mail server Detect geographical patterns
 web
  hasAliveWebServer boolean false none Determines if domain has a web server that responds to PING
sendAssess
 inboxQualityScore decimal false none Inbox quality score Create rules based on result
 sendRecommendation string false none Send recommendation Create rules based on result e.g. 'safe to send', 'block from mailing list'
spamAssess
 isDisposableEmailAddress boolean false none Is the email domain a DEA? Block email or prompt for alternate email address
 isDarkWebEmailAddress boolean false none Is the email address domain hosted in the Dark Web? Block email or prompt for alternate email address
 isGibberishDomain boolean false none Is the email address domain deemed to be gibberish text? Block email or prompt for alternate email address
 isGibberishUser boolean false none Is the email address user deemed to be gibberish text? Block email or prompt for alternate email address
 domainRiskScore decimal false none General risk score of email address domain Create rules based on Trust Score result
 formatRiskScore decimal false none Format risk score of email address Create rules based on Trust Score result
 profanityRiskScore decimal false none Profanity risk score of email address Create rules based on Trust Score result
 overallRiskScore decimal false none Overall risk score for spam from this email address based on the factors above Create rules based on Trust Score result
 actionRecomendation string false none What action should you take if receiving email from email address Create rules based on Trust Score result
 blockLists BlockList[] false none Blocklists Create rules based on Trust Score result
spamTrapAssess
 isSpamTrap boolean false none Is this email address a known spam trap? Block email known to be associated with spam trap activity
 spamTrapDescriptor string false none Description of spam trap (e.g. uceprotect) Identify type of spam trap associated with email address
hippoTrust
 score decimal false none How much can I trust the person associated with this email address? Create rules based on Trust Score result
 level string false none Trust level Create rules based on Trust Score result
social
 gravatar
  imageUrl string false none Image URL if a gravatar is associated with email address
  profileUrl string false none Profile URL if a gravatar is associated with email address
domain string false none none
performance
 syntaxCheck integer false none Processing time to check syntax of email address
 dnsLookup integer false none Processing time to gather and check DNS of email address
 spamAssessment integer false none Processing time to assess email address for spam behavior
 mailboxVerification integer false none Processing time to check mail box of email address
 webInfrastructurePing integer false none Processing time to PING web site of email address
 other integer false none Processing time for miscellaneous processing of email address
 overallExecutionTime integer false none Total processing time
diagnostic
 key string false none none

mx records

Name Type Required Restrictions Description
preference integer false none none
exchange string false none none
ipAddresses string[] false none none

Block lists

Email Hippo includes references to third party spam block lists to enrich it’s own email verification information.

Name Type Required Restrictions Description
blockListName string false none Name of block list
isListed boolean false none Is the email address domain listed in the block list?
listedReason string false none If the email address domain is listed in the block list, then why? (e.g 127.0.1.2)
listedMoreInf string false none Any additional information provided from the block list on reason(s)

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.
None No status available.

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 MailServerFaultDetected An unspecified mail server fault was detected.
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 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.
Unverifiable UpredictableSystem Unpredictable system infrastructure detected. Various email services deliver unpredictable results to email address verification. The reason for this unpredictability is that some email systems elect not to implement email standards (i.e. RFC 2821). For systems that are known to be unpredictable, we return a secondary status of 'UpredictableSystem'.

Email Hippo Trust Score

Type info: List of hippoTrust

For email verification and data enrichment performed to the MORE level, Email Hippo supplies a Trust Score.

The Trust Score provides an ‘at a glance’ determination of quality; drilling deeper than just the email address itself.

The Email Hippo Trust Score is designed to answer a fundamental question posed from the perspective of a business owner, merchant, data broker or lead generation service:

The Trust Score takes dozens of metrics and signals into consideration when making this assessment and providing the final score.

Trust level

Trust Level Description Score range
None No information on trust
Low Low trust level Less than 2.66
Medium Medium trust level 2.66 to 6.99
High High trust level 7 to 10

Other enums

Syntax verification reason codes

Name Description
None No status available.
AtSignNotFound The ‘@’ sign not found.
DomainPartCompliancyFailure The syntax of a legal Internet host name was specified in RFC-952. One aspect of host name syntax is hereby changed: the restriction on the first character is relaxed to allow either a letter or a digit. (http://tools.ietf.org/html/rfc1123#section-2.1) NB RFC 1123 updates RFC 1035, but this is not currently apparent from reading RFC 1035. Most common applications, including email and the Web, will generally not permit escaped strings (http://tools.ietf.org/html/rfc3696#section-2). The better strategy has now become to make the “at least one period” test, to verify LDH conformance (including verification that the apparent TLD name is not all-numeric)(http://tools.ietf.org/html/rfc3696#section-2) Characters outside the set of alphabetic characters, digits, and hyphen MUST NOT appear in domain name labels for SMTP clients or servers (http://tools.ietf.org/html/rfc5321#section-4.1.2) RFC5321 precludes the use of a trailing dot in a domain name for SMTP purposes (http://tools.ietf.org/html/rfc5321#section-4.1.2)
DoubleDotSequence Can’t have empty element (consecutive dots or dots at the start or end)(http://tools.ietf.org/html/rfc5322#section-3.4.1)
InvalidAddressLength Email is too long. The maximum total length of a reverse-path or forward-path is 256 characters (including the punctuation and element separators) (http://tools.ietf.org/html/rfc5321#section-4.5.3.1.3)
InvalidCharacterInSequence Invalid character in email address.
InvalidEmptyQuotedWord Invalid Empty Quoted Word.
InvalidFoldingWhiteSpaceSequence Folding White Space.  local-part = dot-atom / quoted-string / obs-local-part obs-local-part = word (“.” word)(http://tools.ietf.org/html/rfc5322#section-3.4.1)
InvalidLocalPartLength Local part must be 64 characters or less.
InvalidWordBoundaryStart RFC5321 section 4.1.3. Character preceding IPv4 address must be ‘:’. RFC5321 section 4.1.3
Success Syntax verification is successful.
TooManyAtSignsFound Too many @ signs found in email address. Only one is permitted.
UnbalancedCommentParenthesis Unbalanced comment parenthesis
UnexpectedQuotedPairSequence Any ASCII graphic (printing) character other than the at-sign (“@”), backslash, double quote, comma, or square brackets may appear without quoting. If any of that list of excluded characters are to appear, they must be quoted (http://tools.ietf.org/html/rfc3696#section-3) Any excluded characters? i.e. 0x00-0x20, (, ), <, >, [, ], :, ;, @, , comma, period, “
Unknown Syntax verification failed for unknown reasons.
UnmatchedQuotedPair Unmatched quoted pair.

Service type identifier

Code Description
Other Service not of pre-defined list of known types
Aol AOL
Hotmail Hotmail
Gmail Gmail
GoogleForBiz Google for business
MessageLabs Symantec message labs
Net4Sec Net4Sec
Office365 Microsoft Office 365
Yahoo Yahoo
UceProtect UCE Protect

Send assessment

Type info: sendAssess

Email Hippo performs an assessment of the risk associated with sending email to the email address queried. The overall score is based on a number of factors including:

Send recommendation

Code Description
None No recommendation.
SafeToSend Safe to send email. Minimal risk of hard bounces or complaints.
DoNotSend Do not send. Hight risk of hard bounce and complaints.
RiskyToSend Sending to this email address is risky. Hard bounces and complaints are possible. Send at your own risk.

.Net client libraries

We have a .NET package built for easy integration with our MORE Edition 2 (v3) API services. For further information on the RESTful server side implementation, please see the docs and schema.

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

Quick start guide

/* Install */

Install-Package EmailHippo.EmailVerify.Api.V3.Client

Install-Package System.Runtime.Serialization.Primitives

How to get the package

The package is available from Nuget.

How to use the package

/* Licence and initialise */
/*  Visit https://www.emailhippo.com to get a license key */

ApiClientFactoryV3_5.Initialize("{your license key}", {Custom logger factory} [optional]);

Step 1 - license and initialize

This software must be initialized before use. Initializaton is only needed once per app domain. The best place to do this in in the hosting process bootstrap code. For example, a web app use global.asax, a console app use Main() method.

Supply license configuration to the software by providing the license key in code as part of initialization

Invoke static method ApiClientFactoryV3_5.Initialize(string licenseKey = null)... if supplying the license in code.

The logger factory is of type Microsoft.Extensions.Logging and allows integration with Serilog, console, NLog and many more logging providers.

/* Create the client */

var EmailHippoClient = ApiClientFactoryV3_5.Create();

Step 2 - create the client

The main client object is created using a static factory.

/* Use - asynchronously check email addresses */

var responses = await EmailHippoClient.ProcessAsync
    (
       new VerificationRequest 
        { 
            VerificationData = new List<VerificationDataRequest> 
            {
                new VerificationDataRequest { EmailAddress = "[email protected]", ServiceType = ServiceType.More, OtherData = "d1" },
                new VerificationDataRequest { EmailAddress = "[email protected]", ServiceType = ServiceType.More, OtherData = "d2" }
            }
        },
        CancellationToken.None
    );

/*Process responses*/
/*..responses*/

Step 3 - use

Once you have a reference to the client object, go ahead and use it.

This code checks more than one email address asynchronously.

Step 4 - additional functions

/* Progress reporting */

EmailHippoClient.ProgressChanged += (o, args) => Console.WriteLine(JsonConvert.SerializeObject(args));

Progress reporting Progress can be captured using the built in event delegate "ProgressChanged".

/* Logging*/

public class Startup
{
private static readonly ILoggerFactory MyLoggerFactory = new LoggerFactory();

/// <summary>
/// Setup and add serilog listeners to Microsoft logging extensions.
/// </summary>
public Startup(){
    Log.Logger = new LoggerConfiguration()
                    .Enrich
                    .FromLogContext()
                    .WriteTo.LiterateConsole()
                    .CreateLogger();

            MyLoggerFactory
                .AddSerilog();
    }
}

Logging Logging is provided using Microsoft.Extensions.Logging.

Enable logging using standard Microsoft.Extensions.Logging listeners.

WHOIS API

Email Hippo WHOIS API services facilitate easy, fast and scalable access to the global WHOIS databases in both structured and unstructured formats with domain age information.

Consistent, parsed records

WHOIS records are intrinsically designed for humans to read and records come in different formats according to the choices made by an individual Domain Name Registrar and the Domain Name Registry.

For any serious application demanding data in a predictable, consistent machine-readable format, the standard WHOIS system will not work. This is where Email Hippo adds value to the WHOIS system by adding services capable of presenting the relatively chaotic structure of WHOIS records as reliable, predictable and machine-readable formats.

Machine readable dates

For the ultimate in machine integration compatibility, Email Hippo returns dates and durations in ISO 8601 standard formats.

WHOIS Edition 1 - V1

Specification

Item Spec
Manufacturer emailhippo.com
Current version v1
Uptime > 99.99%
Response time >0.2 seconds < 8 seconds. Typical response time 0.7 seconds.
Throughput and concurrency 50 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 Geographically dispersed cloud data centers, auto load balance / failover
Supported Top Level Domains (TLDs) .asia .br .co.uk .com.br .com .de .fr .info .io .in .jp .me.uk .mobi .net .org .org.uk .ru .uk

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 50 WHOIS queries 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:

Large throughput requirement

For sustained throughput of more than 50 domain queries per second, please contact us about a private, dedicated service.

Authentication

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

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

{k}: yourlicensekey

Endpoint - GET WHOIS by domain

# You can also use wget
curl -X GET //api.whoishippo.com/v1/{k}/{d} \
  -H 'Accept: application/json'
const request = require('node-fetch');

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

};

fetch('//api.whoishippo.com/v1/{k}/{d}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});
URL obj = new URL("//api.whoishippo.com/v1/{k}/{d}");
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());
require 'rest-client'
require 'json'

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

result = RestClient.get '//api.whoishippo.com/v1/{k}/{d}',
  params: {
  }, headers: headers

p JSON.parse(result)
import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('//api.whoishippo.com/v1/{k}/{d}', params={

}, headers = headers)

print r.json()
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", "//api.whoishippo.com/v1/{k}/{d}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

<?php

// URL which should be requested
$url = 'https://api.whoishippo.com/v1';

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

$domain = 'Domain to query'; // Domain to query

// jSON String for request
$url .= "/$apikey/$domain";

// 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";

}

?>
#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://api.whoishippo.com/v1";
    /// <summary>
    /// 0 = ApiUrl
    /// 1 = API Key
    /// 2 = Domain to query
    /// </summary>
    private const string QueryFormatString = @"{0}/{1}/{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 domain to query");

        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
}

Query WHOIS records by domain and license key.

GET //api.whoishippo.com//v1/{k}/{d}

GET WHOIS record.

Parameters

Parameter In Type Required Description
k path string true the license key
d path string true the domain to query

Responses (including errors)

Status Meaning Description Schema
200 OK Success WhoisRecord
400 Bad Request Must enter a valid license key and domain to query or; A domain to query is required. None
401 Unauthorized * License key refused or; Key expired or quota exceeded. None
404 Not Found The domain is not found in WHOIS. None
422 Unprocessable Entity Cannot process a fully parsed respone. Top Level Domain (TLD) is not supported. None
429 Too Many Requests Maximum processing rate exceeded. See Concurrency for further information. None
500 Internal Server Error Server error. None

WhoisRecord Schema

{
  "version": {
    "v": "string",
    "doc": "string"
  },
  "meta": {
    "recordCreatedDate": "2018-08-09T10:26:42Z",
    "recordUpdatedDate": "2018-08-09T10:26:42Z",
    "recordAge": "string",
    "recordAgeIso8601": "string",
    "timeToExpiry": "string",
    "timeToExpirySeconds": 0,
    "timeToExpiryIso8601": "string",
    "tld": "string",
    "domain": "string",
    "domainAge": "string",
    "domainAgeSeconds": 0,
    "domainAgeIso8601": "string",
    "parseCode": "string",
    "executionTime": 0
  },
  "whoisServerRecord": {
    "recordFound": true,
    "registrar": {
      "registrarId": "string",
      "name": "string",
      "whois": "string",
      "url": "string",
      "abuseEmail": "string",
      "abusePhone": "string"
    },
    "dnsSec": "string",
    "domainName": "string",
    "tld": "string",
    "domainHandle": "string",
    "domainOwnerContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "adminContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "billingContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "techContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "registrarContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "zoneContact": {
      "userId": "string",
      "name": "string",
      "organization": "string",
      "street1": "string",
      "street2": "string",
      "street3": "string",
      "street4": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phoneNumber": "string",
      "phoneNumberExt": "string",
      "faxNumber": "string",
      "faxNumberExt": "string",
      "email": "string"
    },
    "nameServers": [
      {
        "Address": "string"
      }
    ],
    "domainStati": [
      "string"
    ],
    "remarks": "string",
    "reseller": "string",
    "created": "2018-08-09T10:26:42Z",
    "changed": "2018-08-09T10:26:42Z",
    "expiry": "2018-08-09T10:26:42Z",
    "rawResponse": "string",
    "customFields": [
      {
        "customFieldId": 0,
        "name": "string",
        "value": "string"
      }
    ]
  }
}
Name Type Required Restrictions Description
Version
 v string false none none
 doc string false none none
Meta
 recordCreatedDate datetime false none none
 recordUpdatedDate datetime false none none
 recordAge string false none none
 recordAgeIso8601 string false none none
 timeToExpiry string false none none
 timeToExpirySeconds integer(int64) false none none
 timeToExpiryIso8601 string false none none
 tld string false none none
 domain string false none none
 domainAge string false none none
 domainAgeSeconds integer(int64) false none none
 domainAgeIso8601 string false none none
 parseCode string false none none
 executionTime integer(int64) false none none
WhoisServerRecord
 recordFound boolean false none none
 registrar Registrar false none none
 dnsSec string false none none
 domainName string false none none
 tld string false none none
 domainHandle string false none none
 domainOwnerContact Contact false none none
 adminContact Contact false none none
 billingContact Contact false none none
 techContact Contact false none none
 registrarContact Contact false none none
 zoneContact Contact false none none
 nameServers NameServer[] false none none
 domainStati string[] false none none
 remarks string false none none
 reseller string false none none
 created datetime false none none
 changed datetime false none none
 expiry datetime false none none
 rawResponse string false none none
 customFields CustomField[] false none none

Registrar

Name Type Required Restrictions Description
registrarId string false none none
name string false none none
whois string false none none
url string false none none
abuseEmail string false none none
abusePhone string false none none

Contact

Name Type Required Restrictions Description
userId string false none none
name string false none none
organization string false none none
street1 string false none none
street2 string false none none
street3 string false none none
street4 string false none none
city string false none none
state string false none none
postalCode string false none none
country string false none none
phoneNumber string false none none
phoneNumberExt string false none none
faxNumber string false none none
faxNumberExt string false none none
email string false none none

NameServer

Name Type Required Restrictions Description
Address string false none none

CustomField

Name Type Required Restrictions Description
customFieldId integer(int32) false none none
name string false none none
value string false none none

Enums

ParseCode Values

Value Description
Success WHOIS information found
Notfound No WHOIS information found

Partner integrations

Auth0 integration

The purpose of this function is to prevent new users from signing up to your Auth0 authenticated services with bad or disposable email addresses. Allowing use of email addresses which will hard bounce or are disposable will mean any subsequent attempt at contact with the user after sign-up will fail. Disposable email addresses are an early indicator of fraud.

About the MORE API

You can be up and running with MORE, the Email Hippo API in fifteen minutes or less. MORE delivers 74 datapoints about every email address, so you can filter sign-ups, spot disposable emails and keep your data clean.

About Auth0

Auth0 is an Identity as a Platform (IDaaS) service provider.

Auth0 is Identity made simple and secure. With Auth0, you take perhaps the riskiest endeavor your engineering organization will face, managing and securing the identities of your customers and employees, and abstract away this complexity and risk with our Identity Platform.

Our standards-based Identity-as-a-Service platform is built for developers, by developers so that your engineering organization can focus on building the solutions that delight your customers and drive your revenue.

Our customers find that what typically either takes months to deliver or simply cannot be delivered via internal or external solutions, takes them only days to deliver with Auth0 due to our extensive SDKs, intuitive API, extensible architecture and our simple management dashboard.

This is why Auth0 is the leader in developer-focused Identity Management, with more than 5,000 customers trusting us with billions of transactions everyday.

Auth0 website

Configuration

Prerequisites

  1. An Auth0 account with a tenant setup.

  2. An Email Hippo account with a MORE API subscription and access to your API key.

To create an account and purchase a subscription for the MORE API please sign up.

Configuration on Email Hippo

Once you have a subscription set up and your API key there is no further setup required within Email Hippo.

For further information on the MORE API please read the MORE section on this site.

Configuration on Auth0

  1. Go to the Rules option on the menu.

  2. Under Settings on this page add a new key value.

  3. Set the key as 'HIPPO_API_KEY' and the value as your Email Hippo API key.

  4. Click on ‘+ Create Rule’.

  5. Select the ‘Empty Rule’ template.

  6. Name your rule - for example ‘Email Hippo Email Address Validation’.

  7. Replace the code displayed in Auth0 with the JavaScript shown here. (Select the JavaScript tab to view the code.)

  8. Click on ‘Save’ or ‘Try this rule’ to use the function within your Auth0 sign up form and prevent sign ups with bad or disposable email addresses.

The MORE API (Edition2/Version3) contains multiple data points which you may wish to incorporate in your function, for example for prompting re-input of mis-spelled email addresses.

Our function uses the simple ‘result’ and ‘additional status’ to identify the email addresses which should not be accepted.

Zapier

A Zapier integration for our MORE API is available at Email Hippo Zapier Integrations

About Zapier

Zapier connects apps and automates workflows moving information between your web apps.

Zapier website

Frequently asked questions

How can I get a key?

Click here to sign up and generate a key.

Can I trust you with my data?

Great question. Yes, of course - see our Compliance pages for detailed information.

Will I get blocklisted using your APIs?

No. It’s Email Hippo infrastructure that does the work.

Will anyone know that I am querying a domain or an email address?

No. It’s Email Hippo infrastructure that does the work.

How do I call your APIs?

For a JSON response, make a simple GET request to the endpoint.

Read the endpoint sections for more information and take a look at the code samples, or try it out when you sign up.

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.

Do you cache results?

To deliver the speed and reliability demanded by our customers, verification results are cached as follows:

Service Cache expiration
MORE Edition 1/V2 Up to 30 days
MORE Edition 2/V3 Up to 30 days
WHOIS Edition 1/V1 Up to 90 days (depends on domain expiry in the WHOIS record).

No personally identifiable information is stored in our cache infrastructure.

Can I get my usage in real-time?

Usage is available in the customer portal or for MORE Edition 2/V3 use the quota API.

How does the MORE API 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 verification or any similar SMTP based activity. The reason that any email / SMTP process is difficult from a client perspective is that mail services need to protect themselves from an ever increasing landscape of abuse including spam and DDoS attacks.

Email Hippo‘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 our SMTP verification software stack together with an extensive cloud based infrastructure. That’s why Email Hippo can do the “hard bits” best and offer outstanding coverage on the more technically challenging, dynamic domains.

How does the WHOIS API work?

At a basic conceptual level, the process of querying WHOIS services is very simple. First, find the authoritative WHOIS server for a particular TLD. Next, connect to the server on port 43, query the domain and capture the response.

The hard bit is dealing with WHOIS services that are intrinsically configured to work against the process of querying domains in any form large volume scale. Additionally, the WHOIS system does not follow one, unified standard which means that the data returned from WHOIS services is very difficult to parse to anything that is useful for automation or integration purposes.

Email Hippo’s strength in dealing with the “hard bit” of the WHOIS system comes from years of experience in solving similar challenges in email verification.

What comes back from the API?

Various text or binary response formats.

Note: For a detailed explanation of the responses available, see the appropriate service Edition/Version Schema on this site.

Can your email validation APIs find spam traps?

A spam trap is a moving target. In theory (and indeed in practice) anyone can setup a block List and start putting spam traps into the wild.

Email Hippo has spam trap detection 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, Email Hippo provides the best spam trap detection capabilities available.

Glossary

ACL

Access Control List.

An ACL determines what networking traffic is allowed to pass and what traffic is blocked.

An ACL change is sometimes required to your company firewall in order to access our API.

API

Application Programmers Interface.

See Wikipedia - API Definition for further 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.

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 Outlook, Yahoo, AOL, Gmail etc.

Business to consumer refers to the activity of businesses sending email to clients using consumer email addresses.

Verifying email addresses in consumer domains is generally more technically challenging than B2B

Block list

See DNSBL.

BSON

Binary Object Notation

See Wikipedia - BSON for further information.

CORS

Cross Origin Resource Scripting

Allows modern browsers to work with script (e.g. JavaScript) and JSON data originating form other domains.

CORS is required to allow client script such a JavaScript, jQuery or AngularJS to work with results returned from an external RESTful API.

See Wikipedia - CORS for more information.

DDoS

Distributed Denial of Service

See Wikipedia - Denial-of-service attack for further information.

DEA

Disposable Email Address

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

DEAs should not be regarded as valid for email send purposes as it is unlikely that messages sent to DEAs 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 the MX records needed to locate a domains mail servers.

See Wikipedia - Domain Name System for further information.

DNSBL

DNS Block List

As an anti-spam measure, mail servers can use spam block 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.

See Wikipedia - DNSBL for further information.

ESP

Email Service Provider

A service that sends emails on your behalf.

See Wikipedia - Email service provider (marketing) for more information.

Free mail

Addresses served by popular B2C service providers such as Outlook, Yahoo, Live, AOL, Gmail and so on.

Greylisting

A technique used in mail servers as an anti-spam technique. Sometimes also known as “deferred”, greylisting arbitrarily delays the delivery of emails with a “try again later” response to the client sending the email.

See Wikipedia - Greylisting for more information.

HTTP

Hypertext Transfer Protocol

See Wikipedia - Hypertext Transfer Protocol for more information.

IP address

Internet Protocol Address

See Wikipedia - IP Address for more information.

ISO 3166

International standard for country codes.

See Country Codes - ISO 3166 for 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.

See Wikipedia - JSON for 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 here to sign up and access a license key.

ms

Milliseconds.

MX

Mail Exchanger

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

NDR

Non Delivery Report

A message that is returned to sender stating that delivery of an email address was not possible.

See Wikipedia - Bounce message for more information.

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

protobuf

Protocol Buffers is a method of serializing structured data.

See Wikipedia - Protocol Buffers for more information.

Punycode

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

See Wikipedia - Punycode for more information.

RESTful

Representational state transfer

See Wikipedia - RESTful for more information.

RFC

Request for Comments

The principal technical development and standards-setting bodies for The Internet.

See Wikipedia - Request for Comments for more information.

Role address

A role address is a generic mailbox such as [email protected], [email protected] used by organizations to manage email messages of similar organizational types. For example, email messages sent to [email protected] can be routed to an organizations sales team where a team of sales people can deal with enquiries.

Role addresses allow collaborative working based on groups rather than indiviidual mailboxes.

SLA

Service Level Agreement

See Wikipedia - SLA for more information.

See our Service Level Agreement.

SMTP

Simple Mail Transport Protocol

SMTP is a protocol. It is the sequence of commands and responses between a client (the software sending an email) and server (the software receiving an email) that facilitates the sending and receiving of email between computer based email messaging systems.

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.

See Wikipedia - Spam traps for more information.

TXT

TXT records associate arbitary and unformatted text with a domain. TXT records uses include Sender Policy Framework (SPF) and other domain validation applications.

See Wikipedia - TXT record for more information.

XML

e(X)tensible Markup Language

See Wikipedia - XML for more information.