Technical Overview test
-
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
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
- Gibberish Detection
- A common vector for persons wishing to remain anonymous is to register or use a pre-existing domain. Finding an available domain is not easy and as such, many opt for a ‘Gibberish’ domain such as
sdfre45321qaxc.com
. - Email Hippo detects gibberish in both the user and domain elements of an email address.
- A common vector for persons wishing to remain anonymous is to register or use a pre-existing domain. Finding an available domain is not easy and as such, many opt for a ‘Gibberish’ domain such as
- Consumer or Business assessment - Email Hippo assesses whether the email address is likely to be from a consumer or a business and presents the result as a score from 0 to 10. The closer the score is to 0 the more likely the email address belongs to a consumer, the closer it is to 10 the more likely it is to belong to a business.
- Returns:
- Primary and secondary results codes
- Role, free, gibberish, gender and disposable identifiers
- Consumer or Business assessment
- Block list checks
- Server configuration analysis (DNS, Mx, location and infrastructure)
- New Anti-Spam system result status
- 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 | v1 |
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 |
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 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 INSIGHT uses API keys to allow access to the API. API keys can be managed within Hippo World.
Email Hippo INSIGHT 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 - GET assessment result
Performs email address verification and assessment to the full data enrichment level and returns the data in four formats:
-
JSON
GET //api.hippomore.com/v4/json/{apiKey}/{emailAddress}
GET ASSESS result.
Parameter | In | Type | Required | Description |
---|---|---|---|---|
apiKey | path | string | true | the license key |
emailAddress | path | string | true | the email address |
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
{
"version": {
"v": "1.0.409"
},
"meta": {
"email": "string"
},
"emailAddressAnalysis": {
"mailboxVerification": {
"result": "string",
"secondaryResult": "string"
},
"syntaxVerification": {
"isSyntaxValid": true
},
"disposition": {
"isGibberish": true,
"isProfanity": true,
"isRole": true,
"isSubaddressing": true,
"isFreeMail": true,
"isDisposable": true,
"hasCatchAllServer": true,
"hasBeenBlocked": true
},
"assessments": {
"consumerBusiness": 0
}
},
"domainAnalysis": {
"disposition": {
"isSubDomain": true,
"isGibberish": true,
"isProfanity": true,
"isDarkWeb": true,
"hasBeenBlocked": true,
"hasDnsRecords": true,
"hasMxRecords": true,
"mailServerLocation": "string",
"mailServerInfrastructure": "string"
}
}
Result record schema
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
Version | ||||
v | string | false | none | Contains details of the version and edition of API |
Meta | ||||
string | false | none | The email being queried | |
email Address Analysis | ||||
mailboxVerification | ||||
result | string | false | none | Primary result codes |
secondaryResult | string | false | none | Secondary result codes |
syntaxVerification | ||||
isSyntaxValid | boolean | false | none | Is the syntax of the email address correct according to RFC standards? |
disposition | ||||
isGibberish | boolean | false | none | Is the email address deemed to be gibberish text? |
isProfanity | boolean | false | none | Is the email address deemed to be profanity? |
isRole | boolean | false | none | Is a role address? (e.g. info@, sales@, postmaster@) |
isSubaddressing | boolean | false | none | Does the email contain subaddressing i.e. + some text or (some text) |
isFreeMail | boolean | false | none | Is a free mail provider? (e.g. gmail, hotmail etc) |
isDisposable | boolean | false | none | Is the email address a disposable email address? |
hasCatchAllServer | boolean | false | none | Is the mail server a catch all mail server? |
hasBeenBlocked | boolean | false | none | Is the email address on a reputable block list? |
assessments | ||||
consumerBusiness | decimal | false | none | Does the email address relate to a consumer or a business? Consumer 0-4, Business 6-10 |
domainAnalysis | ||||
disposition | ||||
isSubDomain | boolean | false | none | Is a subdomain being used in the email address? |
isGibberish | boolean | false | none | Is the domain deemed to be gibberish text? |
isProfanity | boolean | false | none | Is the domain deemed to be profanity? |
isDarkWeb | boolean | false | none | Has the domain been associated with the Dark Web? |
hasBeenBlocked | boolean | false | none | Is the domain on a reputable block list? |
hasDnsRecords | boolean | false | none | Does the domain have any DNS records? |
hasMxRecords | boolean | false | none | Does the domain have any MX records? |
mailServerLocation | string | false | none | Mail server location as a 2 digit ISO code (e.g. US) |
mailServerInfrastructure | string | false | none | Infrastructure Identifier (e.g. Hotmail, GoogleforBiz, Office365, Mimecast) |
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). |
Disposable email address | The email address is provided by a well known disposable provider |
Unverifiable | Conclusive verification result cannot be achieved due to mail server configuration or anti-spam measures. |
Secondary reason codes
Primary code | Secondary reason | Description |
---|---|---|
Ok | Success | Successful verification. 100% confidence that the mailbox exists. |
Bad | DomainDoesNotExist | 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 | EmailAddressFoundOnBlockLists | The email address is found on one or more block lists. |
Bad | EmailContainsInternationalCharacters | Email address contains international characters. |
Bad | InvalidEmailFormat | Invalid email address format. |
Bad | MailboxDoesNotExist | The mailbox does not exist. 100% confidence that the mail box does not exist. |
Bad | MailboxFull | 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 | MailServerFaultDetected | An unspecified mail server fault was detected. |
Bad | NoMailServersForDomain | 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 | 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. |
Disposable email address | 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 | MailServerAntiSpam | The email server is using anti-spam measures. Anti-spam systems and processes can include: proxy based, hosted anti-spam such as ProofPoint or MimeCast; self hosted anti-spam using remote data services such as Barracuda, SORBS or SPAMCOP; and Whitelist based systems only allow emails from pre-approved sender email address. Pre-approval of sender email addresses can be done manually by the email system administrator and/or automatically via "click this link" to confirm your email address type opt-in emails. |
Unverifiable | MailServerGreyListing | Greylisting is in operation. It is not possible to validate email boxes in real-time where greylisting is in operation. |
Unverifiable | MailServerCatchAll | 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 | None | No additional information is available. |
Unverifiable | Timeout | The remote email server timed out. Mail server is too busy / overloaded, misconfigured, offline or otherwise unavailable. |
Unverifiable | UnpredictableSystem | 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'. |
Consumer Business assessment
.Net client libraries
Pre-requisites and the package
We have a .NET package built for easy integration with our ASSESS Edition 1 (v1) 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.
- Visual Studio 2017 or later
- .NET Standard 2.0 or later
- API license key
The package is available from Nuget.
Example custom code snippets
* © 2020, Email Hippo Limited. (http://emailhippo.com)
# You can also use wget
curl -X GET https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}
-H 'Accept: application/json'
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/
<?php
require 'vendor/autoload.php';
$headers = array(
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_body = array();
try {
$response = $client->request('GET','https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}', array(
'headers' => $headers,
'json' => $request_body,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
?>
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/
const headers = {
'Accept':'application/json'
};
fetch('https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/URL obj = new URL("https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}");
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());
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/require 'rest-client'
require 'json'
headers = {
'Accept' => 'application/json'
}
result = RestClient.get 'https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}',
params: {
}, headers: headers
p JSON.parse(result)
# © 2020, Email Hippo Limited. (http://emailhippo.com)
import requests
headers = {
'Accept': 'application/json'
}
r = requests.get('https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}', headers = headers)
print(r.json())
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/
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", "https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
/*
* © 2020, Email Hippo Limited. (http://emailhippo.com)
*/
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }
/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}
/// Make a dummy request
public async Task MakeGetRequest()
{
string url = "https://api.hippomore.com/v4/json/{apiKey}/{emailAddress}";
var result = await GetAsync(url);
}
/// Performs a GET Request
public async Task GetAsync(string url)
{
//Start the request
HttpResponseMessage response = await Client.GetAsync(url);
//Validate result
response.EnsureSuccessStatusCode();
}
/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();
//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
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 free. Register today for 100 free email validations. No credit card details needed to create your account.