How to protect your site from temporary mails using api.testmail.top?

API: Check Domain/Email mailbox address

URL: https://api.testmail.top/domain/check
Method: GET
Example request: https://api.testmail.top/domain/check/data=example@mail.com&ip=8.8.8.8
Headers: Authorization: Bearer XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX

Parameters of request

Headers of request

Let's get down to practice

Let's look at the requests to api.testmail.top by examples. To try to send from a request to check a deliberately false domain/email, taken from one of the most popular temporary mail services temp-mail.org, from the console

cURL request:

					curl --location --request GET 'https://api.testmail.top/domain/check?data=fovah86335@990ys.com&ip=154.115.9.195' \

--header 'Authorization: Bearer XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX'
					
				

cURL response:

					{
    "error": 0,
    "result": false,
    "message": "This domain is in Blacklist"
}
					
				

The response received "result": false - which means that this user CANNOT be allowed to register

---

Now, let's try to send a request for domain/email verification using PHP. As in the previous example, there is nothing difficult, now, for example, let's send 100% GMAILtrust mail. On my own I recommend setting the CURLOPT_TIMEOUT parameter to 3 seconds, although a regular request takes a split second - this will protect your registration from crashing if the api.testmail.top server is unavailable

PHP - cURL request:

					<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.testmail.top/domain/check?data=typicaluser@gmail.com&ip=154.115.9.195',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 3,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
					
				

PHP - cURL response:

					{
    "error": 0,
    "result": true,
    "message": "This domain is in Whitelist"
}
					
				

In response, we received "result": true - this means that this user MAY be allowed to register

Great, now let's dive a little deeper into the capabilities of api.testmail.top, consider a few exceptions:

In the two previous examples, we looked at typical mails that represent BLACKLIST (temporary mails contained in our database) and WHITELIST (such as GMAIL, YAHOO or YANDEXfor example ...). But what to do in a non-standard situation?

1. The mail domain has the "UNKNOWN" status so far

   The user sends mail of his personal or corporate domain, for example admin@habr.ru, in this case the answer will be as follows:

   								{
   "error": 0,
   "result": true,
   "unknown": true,
   "message": "Unknown domain. We will classify this domain shortly"
   }
   								
   							

   In response, we received "result": true - which means that this user MAY be allowed to register, since we do not yet know exactly what kind of domain it is, and we cannot "scatter" our clients. After that, the domain will be sent for verification, it must be defined, so that when you repeat the request, you can already answer exactly whether it belongs to any of the lists.

2. User made a (syntactic) error while entering mail in the registration form

   For example admin@;habr.ru, in this case the answer will be as follows:

   								{
       "error": 31,
       "result": false,
       "message": "Invalid email address"
   }
   								
   							

   In response, we received "result": false- which means that this user CANNOT be allowed to register. In this case, you need to handle the error "error": 31 - which will prompt your user to check the correctness of the email address entered by him

3. Or is his mail domain not capable of receiving mail at all?

   For example admin@habr1.ru, in this case the answer will be as follows:

   								{
       "error": 36,
       "result": false,
       "message": "No mail server is attached to this domain"
   }
   								
   							

   In response, we received "result": false- which means that this user CANNOT be allowed to register. In this case, you need to handle the error "error": 36 - which will prompt your user to check the correctness of the email address entered by him

In any incomprehensible situation, just tell the user to check the correct spelling of EMAIL

This is necessary so that there is no false expectation on the part of the user of the final stage of registration - confirmation of mail