Technical Overview

Technical features
  • Progressive verification using multiple verification processes including:

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

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

    • Hotmail
    • Yahoo
    • Office 365
    • AOL
    • Yandex

  • Spam trap detection - Email Hippo has developed technology that can effectively identify any probable Spam Trap.

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

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

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

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

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

 

Name Type Required Restrictions Description
preference integer false none none
exchange string false none none
ipAddresses string[] false none none
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

 

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:

  • 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

 

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

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

The package is available from Nuget.

How to use the package
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. 

Step 2 - create the client

The main client object is created using a static factory.

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 - Progress can be captured using the built in event delegate "ProgressChanged".
 

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 freeRegister today for 100 free email validations. No credit card details needed to create your account.