APIs Documentation

How To Use Email Score API

Check email reputation programatically. Our propriatory algorirthm 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.

 

Email Score API

Scoring is not a realtime process as we are doing multiple checks before returning the result to you. For this reason 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
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 in 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.