It’s possible to customize and install SafetyMails’ email verification API with code in the programming language of your choice and the access keys. This will enable real-time email verification for various services such as landing pages, point-of-sale forms, applications, and more. By default, SafetyMails responds to query calls, providing the requested information.
Registering an Origin for the Email Verification API:
Remember that for this email verification API to work, you need to have an activated credit subscription (see how to subscribe).
To start the process, follow these steps:
- Log in to your SafetyMails account (If you don’t have an account, create one now and get 100 free credits).
- In the top menu, click on “Real-time API.”
- Select the “For Developers” option.
On the next screen, give a name to the origin you are creating. Register the domain of your form (for example, if your form is located at “https://safetymails.com/form,” you should enter only “safetymails.com”).
After entering the information, the API Key and Origin Ticket will be displayed for use in your script or web service.
Example of Origin Ticket and API Key:
APIKey
55a89975b74************75217b0a2eae840bd
Origin Ticket
b440e8d30f068************3d08b84afe2fe50
Query Syntax
The code used in the email verification API to make queries should follow the following syntax:
https://optin.safetymails.com/main/safetyapi/<API KEY>/<SITE TICKET>/<ENCODED EMAIL>
Where:
onde:
| <COMANDO> | Parameter that specifies the method used in the query. |
| <API KEY> | Access key associated with your SafetyMails account. |
| <TICKET SITE> | Access key associated with the registered query origin. |
| <EMAIL CODIFICADO> | The email must be encoded using the “base64” protocol; otherwise, the system will not receive the data perfectly. |
Usage Examples:
Example JavaScript Code
<meta charset='utf-8'>
<script src='https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js'></script>
<label class='control-label'>E-mail</label>
<input type='text' name='Email' value='' class='email' />
<input type='submit' class="btn-teste" value='Validar E-mail'/>
<script>
let apiKey = '*****************************************';
let tkOrigem = '*****************************************';
$(".btn-teste").click(function(){
let email = btoa($(".email").val());
let url= `https://optin.safetymails.com/main/safetyapi/${apiKey}/${tkOrigem}/${email}`;
$.ajax({
async: false,
type: "GET",
url: url,
timeout: 5000,
success: function (response) {
if(!response.Success) {
console.error("Response error", response);
return;
}
console.log("Response success", response);
},
statusCode: {
429: function() {
console.error("HTTPCode 429");
},
406: function() {
console.error("HTTPCode 406");
},
403: function() {
console.error("HTTPCode 403");
},
402: function() {
console.error("HTTPCode 402");
},
401: function() {
console.error("HTTPCode 401");
},
400: function() {
console.error("HTTPCode 400");
}
}
});
});
</script>Example PHP Code
<?php
$emailEncoded = base64_encode('[email protected]');
$apiKey = '*****************************************';
$tkOrigem = '*****************************************';
$url = "https://optin.safetymails.com/main/safetyapi/{$apiKey}/{$tkOrigem}/{$emailEncoded}";
$process = curl_init($url);
curl_setopt($process, CURLOPT_HEADER, 0);
curl_setopt($process, CURLOPT_FRESH_CONNECT, 1);
curl_setopt($process, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($process, CURLOPT_FORBID_REUSE, 1);
curl_setopt($process, CURLOPT_TIMEOUT, 5);
curl_setopt($process, CURLOPT_ENCODING, '');
$result = curl_exec($process);
curl_close($process);
$httpCode = curl_getinfo($process, CURLINFO_HTTP_CODE);
echo "<?pre>";
print_r($result);
switch ($httpCode) {
case 400:
echo "
HTTPCODE [{$httpCode}] Parâmetros inválidos";
break;
case 401:
echo "
HTTPCODE [{$httpCode}] API Key inválida";
break;
case 402:
echo "
HTTPCODE [{$httpCode}] Créditos insuficientes para a consulta";
break;
case 403:
echo "
HTTPCODE [{$httpCode}] Acesso de uma origem diferente da cadastrada";
break;
case 406:
echo "
HTTPCODE [{$httpCode}] Ticket Origem inválido ou inativo";
break;
case 429:
echo "
HTTPCODE [{$httpCode}] Limite de consultas por hora ou minuto ultrapassado";
break;
}
exit;
Examples of Email Verification API Return Messages
The query returns results in JSON format, as shown in the table below:
| Success: | A boolean return (true or false) indicating whether the call was successful. |
| DomainStatus: | Status of the queried email’s domain. |
| Status: | Email validation result in case of success. |
| Email: | Queried email. |
| Limited: | Indicates if the queried email is from a limited provider, meaning it receives a limited number of requests. |
| Public: | Indicates whether the queried email is a ‘Corporate’ domain (private domains and/or those with private rules for receiving) or an ‘Email provider’ domain (domains with public rules for receiving). |
| Advice: | SafetyMails’ suggested classification for the queried email’s status (Valid, Invalid, Risky, or Unknown). |
| Balance: | The number of credits available for queries in your account. |
| MsgErro: | Returns the error message related to call failure (only when the call encounters an error). |
Return in case of a successful query
{
"Success":true,
"Email":"[email protected]",
"Referer":"www.safetymails.com",
"DomainStatus":"VALIDO",
"Status":"VALIDO",
"Advice":"Valid",
"Public":null,
"Limited":null,
"Balance":4112343
}
Return in case of an error in the query
{
"Success":false,
"Email":"[email protected]",
"Referer":"www.safetymails.com",
"Status":"PENDENTE",
"Advice":"Unknown",
"Msg":"Referer inválido"
}Email Verification API Error Messages
Pay attention to the following error messages:
| HTTPCode | Erro | Descrição |
|---|---|---|
| 400 | Invalid Parameters | Incorrect or non-existent access keys. |
| 401 | Invalid API Key | Incorrect or non-existent access keys. |
| 406 | Invalid or Inactive Origin Ticket | You are trying to make queries for an inactive API origin. Go to your dashboard and activate the origin correctly. |
| 403 | Different Origin Than Registered (%s)<>(%s) | You are trying to make queries for an API origin different from what is registered in your account. Check the origin and try again. |
| 429 | Exceeded Hourly, Minute, or Daily Query Limit – Contact Support | To protect your form from misuse, your API allows only a total of 20 daily queries from the same IP address (default). To make more queries than the allowed limit, contact support ([email protected]) |
| 402 | Insufficient Credits for the Query | Your account does not have enough credits to perform the query. You need to purchase credits. |
Se precisar de mais orientações para customizar sua API de verificar emails, entre em contato com a nossa equipe de suporte ([email protected])