Technical Overview
-
Progressive verification using multiple verification processes including:
- Syntax checking
- DNS checking
- Block-list checking (e.g. spamhaus)
- Web infrastructure checking
- Mailbox checking
-
Unrivalled coverage - Email Hippo leverages the advantages of its scalable infrastructure to provide coverage of domains that are technically challenging. Consumer facing domains tend to be more challenging to cover then business facing domains B2C domains including:
- Hotmail
- Yahoo
- Office 365
- AOL
- Yandex
-
Spam trap detection - Email Hippo has developed technology that can effectively identify any probable Spam Trap.
-
Disposable email address detection - Unrivalled disposable email address detection built on Email Hippo’s proprietary multi-vector real-time analysis:
- Real-time detection of disposable email address providers that employ obfuscation techniques (e.g. rotating domains, IP addresses and MX servers)
- Checking against static lists
- Proprietary scoring and risk assessment
- Send risk assessment scoring based on Email Hippo proprietary scoring heuristics
- Spam assessment and block-list risk scoring based on Email Hippo rules and 3rd party data sources including SpamHaus
- Proprietary risk scoring including assessment of risks for receiving email from (spam), sending email to (send score) and overall risk assessment
- Overall risk scoring based on Email Hippo assessment of Send Risk combined with spam assessment
- 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
- Returns:
- Primary and secondary results codes
- Role, free, gibberish, infrastructure and disposable identifiers
- Detailed technical records including MX records
- Email Hippo trust score
- 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 | v3 |
Uptime | > 99.99% |
Response time | >0.2 seconds < 8 seconds. Typical response time 0.4 seconds. |
Maximum wait time | 90 seconds. This is the maximum time we'll wait for email servers to respond. |
Throughput and concurrency | 220 TPS(Transactions Per Second) |
Security and encryption | Transport security using HTTPS. Data at rest encrypted using 256-bit AES encryption. |
Integration | RESTful GET over HTTPS, XML GET over HTTPS, BSON over HTTPS, protobuf over HTTPS |
Authentication | License key |
Infrastructure | Dispersed cloud data centers, auto load balance / failover. |
Concurrency
To preserve the operational integrity of the service to all of our customers, there is a maximum concurrency enforced by our systems.
Limits
Allowed throughput is 220 MORE email validation requests per second.
Throughput exceeding these limits will receive HTTP response code 429 (too many requests) for subsequent requests for a duration of one minute.
Suggestions on how to manage throughput
If you experience or anticipate exceeding throughput limits, here are two ways to control query rates:
-
Test your integration with representative production loads over a period of time. Monitor response codes for any 429’s. If you see any 429’s please reduce the rate at which your application is querying our servers.
-
For applications that can tolerate slight delays in your data processing mesh, consider using queuing infrastructure with a rate controllable processor. Your ‘processor’ can then schedule picking work off the queue and submitting requests to our systems at a controllable rate.
Large throughput requirement
For sustained throughput of more than 220 queries per second, please contact us.
Authentication
Email Hippo MORE uses API keys to allow access to the API.
Email Hippo MORE expects the API key to be included in all API requests to the server.
{k}: yourlicensekey
You must replace yourlicensekey with your personal API key.
Endpoint - GET quota usage
Retrieves the current usage details for a given license key.
GET //api.hippoapi.com/customer/reports/v3/quota/{k}
GET QUOTA record
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 response. | None |
500 | Internal Server Error | Server error. | None |
JSON Response
{
"accountId": 0,
"licenseKey":"string",
"quotaUsed": 0,
"quotaRemaining": 0,
"nextQuotaResetDate": "2018-08-09T10:26:42Z",
"reportedDate": "2018-08-09T10:26:42Z",
"errorSummary": "string"
}
Quota record schema
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 |
Example custom code snippets
/*
* © 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)
*/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);
});
/*
* © 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)
*/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());
/*
* © 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)
*/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)
# © 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)
*/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)
// ...
}
/*
* © 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
}
Endpoint - GET email address verification result
Performs email address verification to the full data enrichment level and returns the data in four formats:
-
JSON
GET //api.hippoapi.com//v3/more/json/{k}/{e}
-
BSON
GET //api.hippoapi.com//v3/more/bson/{k}/{e}
-
XML
GET //api.hippoapi.com//v3/more/xml/{k}/{e}
-
Protobuf
GET //api.hippoapi.com//v3/more/proto/{k}/{e}
GET email verification result
Parameter | In | Type | Required | Description |
---|---|---|---|---|
k | path | string | true | the license key |
e | path | string | true | the email address to validate |
Responses (including errors)
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Success | ResultRecord |
400 | Bad Request | Bad request. The server could not understand the request. Perhaps missing a license key or an email to check? Conditions that lead to this error are: No license key supplied, no email address supplied, email address > 255 characters, license key in incorrect format. | None |
401 | Unauthorised | Possible reasons: The provided license key is not valid, the provided license key has expired, you have reached your quota capacity for this account, this account has been disabled. | None |
429 | Too many requests | Maximum processing rate exceeded. See Concurrency for further information. | None |
500 | Internal Server Error | An error occurred on the server. Possible reasons are: license key validation failed or a general server fault. | None |
JSON Response
{
"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"
}
}
Result record schema
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 | |
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. info@, sales@, postmaster@) | 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 | |||||
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 |
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) |
mx records
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 | 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 'UnpredictableSystem'. |
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:
- How much can I trust the person associated with this email address?
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 |
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
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:
-
If the domain is determined to be a DEA
-
If the mailbox is verified as ‘Ok’ or ‘Good’
-
Whether the email domain is listed in third party lists (e.g. SpamHaus)
-
Whether the domain is determined to be FreeMail or is a role address
-
Whether the domain has a working web site
Send recommendation
.Net client libraries
Pre-requisites and the package
- Visual Studio 2017 or later
- .NET Standard 2.0 or later
- API license key
The package is available from Nuget.
How to use the package
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.
Step 2 - create the client
The main client object is created using a static factory.
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
Logging - Logging is provided using Microsoft.Extensions.Logging. Enable logging using standard Microsoft.Extensions.Logging listeners.
Example custom code snippets
/* © 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)
*/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);
});
/*
* © 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)
*/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());
/*
* © 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)
*/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)
# © 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)
*/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)
// ...
}
/*
* © 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
}
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.