Email Score API Documentation

How To Use Email Score API

Check email reputation programatically. Our proprietary algorithm will score any email address, including detection of free email service.

Email Score API use case

In case you are dealing with a lot of signups on your website and you want to give special treatment to VIP users, our Email Score API can detect high-profile email addresses.

For detailed code examples that will help you use Email Score API, see our code examples page.

Email Score API

Scoring is not a real-time process, as we are doing multiple checks (including a parsed Whois record check) before returning the result to you. Making an API request is, therefore, a bit different than our other API checks. There are 2 steps:

1. Send email for scoring (Set task API);
2. Check the scoring state (Get result API).

These two APIs are described in detail below. Keep in mind that making a request to “Get result API” and skipping the first step will result in an empty reply.

We provide a webhook solution if you would like to get notified when the result is ready.

More details about using webhook are below.

Set Task API

Get Result API

Email Score how to use 2

Webhook support

If you like to receive the processing result to your URL as soon as it’s ready add “webhook_url” parameter to the API request like this:

http://api.whoapi.com/?email=noreply@whoapi.com&r=emailscore&apikey=yourkey&webhook_url=https://yourwebsite.com/yourscript

Our system will make POST request to the specified URL passing JSON in the request body, like this:

[{“id”:9673,”email”:”noreply@whoapi.com”,”overall_score”:68,”temp_email_service”:false,”score_description”:”Good”}]

The body will contain Array of all emails as Objects. Object fields match API reply fields.

Webhook system supports requests resending in case your URL is not accessible (any HTTP error). In this case, we will make 5 retries with the following delays: 5, 15, 30, 60, 60 minutes.

Let’s make an example request:

http://api.whoapi.com/?email=noreply@whoapi.com&r=emailscore&apikey=demokey

Output JSON format:

{
  "status": 0,
  "results": [ {
    "id": 123,
    "email": "noreply@whoapi.com"
 } ],
  "requests_available": 100
}

http://api.whoapi.com/?email=noreply@whoapi.com&r=emailscore&apikey=demokey&asxml

Output in XML format:

<?xml version="1.0"?>
<response>
  <status>0</status>
  <results>
        <item0>
          <id>123</id>
          <email>noreply@whoapi.com</email>
        </item0>
  </results>
  <requests_available>100</requests_available>
</response>

Parameters meaning

results – array of accepted entries;
id – ID of the accepted entry (used in webhook requests);
email – email address.

http://api.whoapi.com/?email=noreply@whoapi.com&r=emailscore-check&apikey=demokey

Output in JSON format:

null

http://api.whoapi.com/?email=noreply@whoapi.com&r=emailscore-check&apikey=demokey&asxml

Output in XML format:

Parameters meaning

results – array of processed entries;
id – ID of the processed entry (same as in the initial request);
email – email address;
overall_score – score for the email (higher is better);
temp_email_service – true in case this address is provided by temp email service;
score_description – textual score description.