Início » How to create and install a Custom SafetyMails’ real time verification API for registration forms and webservices

How to create and install a Custom SafetyMails’ real time verification API for registration forms and webservices

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:

  • 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])

More Reading

Post navigation