You can create and install a custom SafetyMails API, with code in the programming language of your choice and with SafetyMails access keys, which will serve for real-time verification of emails on various services, whether landing pages, point-of-sale forms, applications, etc. By default, SafetyMails will answer query calls, returning the requested information.
Registering a source:
Remember that for this API to work you need to have a credit subscription activated (see how to subscribe).
To start the process just follow these steps:
- Log into your Safetymails account (If you don’t have an account, create one now and get 100 free credits);
- On the top menu, click on “Real-time API”
- Select the “For Developers” option
- On the next screen, give the origin you are creating a name;
- Enter the domain of your form (for example, if your form is at “https://safetymails.com/form“, you should just enter “safetymails.com“);
- After entering the information the API Key and Source Ticket keys will be displayed for use in your script or Webservice.
Example of Ticket Origin and API Key
APIKey
55a89975b74************75217b0a2eae840bd
Ticket Origin
b440e8d30f068************3d08b84afe2fe50
Query Syntax
The code used to perform the verification queries should follow the following syntax:
https://optin.safetymails.com/main/safetyapi/<API KEY>/<TICKET WEBSITE>/<ENCRYPTED EMAIL>
where:
| <COMMAND> | Parameter that informs the method used in the query. |
| <API KEY> | Access key linked to your SafetyMails account. |
| <TICKET WEBSITE> | Access key linked to the registered query source. |
| <ENCRYPTED EMAIL> | The e-mail must be encrypted using the “base64” protocol, otherwise the system will not receive the data perfectly. |
Examples of use:
JavaScript example
<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>PHP example
<?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;
Return message examples
The return of the queries is in JSON format, according to the table below:
| Success: | Return of type bool (true or false), which tells you whether the call was successful. |
| DomainStatus: | Domain status of the queried e-mail. |
| Status: | Result of email validation, if successful. |
| Email: | Verified email address |
| Limited: | It tells you whether the e-mail queried is from a limited ISP, i.e. one that receives a limited number of requests. |
| Public: | Informs whether the email queried is from the ‘Corporate’ domain (private domains and/or domains that have private rules for receiving) or ‘Email provider’ (domains that have public rules for receiving). |
| Advice: | SafetyMails’ suggested classification for the status of the queried e-mail (Valid, Invalid, Risky or Unknown). |
| Balance: | Number of credits available in your account. |
| MsgErro: | Returns the error message regarding the failed call (only when the call presents an error). |
Return in case of 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 query error
{
"Success":false,
"Email":"[email protected]",
"Referer":"www.safetymails.com",
"Status":"PENDENTE",
"Advice":"Unknown",
"Msg":"Referer inválido"
}Error messages
Look out for the following error messages:
| HTTPCode | Error | Description |
|---|---|---|
| 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 perform queries for an inactive API source. Go to your dashboard and activate the source properly. |
| 403 | Origin different from the registered origin (%s)<>(%s): | You are trying to perform queries for a different API source than the one registered in your account. Check the source and try again. |
| 429 | Query limit per hour or minute or daily exceeded – Contact Support | To protect your form from misuse, your API only allows a total of 20 queries per day from the same IP (default). To make more queries than this, please contact support ([email protected]) |
| 402 | No credits to perform the research | Your account has no credits to perform the query. É preciso adquirir créditos. |
If you need further advice, please contact our support team ([email protected])