Início » Como customizar a API de verificar emails para formulários e webservices

Como customizar a API de verificar emails para formulários e webservices

É possível customizar e instalar a API de verificar emails da SafetyMails, com um código na linguagem de programação que desejar e com as chaves de acesso, que servirá para a verificação em tempo real de emails em diversos serviços, sejam landing pages, formulários em pontos de venda, aplicativos, etc. Por definição, a SafetyMails responderá a chamadas de consultas, retornando as informações solicitadas.

Cadastrando uma origem para a API de verificar emails:

Lembre-se de que para que esta API de verificar emails funcione é necessário ter uma assinatura de créditos ativada (veja como contratar).

Para iniciar o processo basta seguir os seguintes passos:

  • Na tela seguinte, dê um nome à origem que você está criando;
  • Cadastre o domínio do seu formulário (por exemplo, se seu formulário estiver em https://safetymails.com/form”, você deve inserir apenas “safetymails.com”);
  • Após inserir as informações serão exibidas as chaves de API Key e Ticket Origem para utilização em seu script ou Webservice.

Exemplo de Ticket origem e API Key

APIKey
55a89975b74************75217b0a2eae840bd

Ticket Origem

b440e8d30f068************3d08b84afe2fe50

Sintaxe de consulta

O código utilizado na API de verificar emails para realizar as consultas deverá seguir a seguinte sintaxe:

https://optin.safetymails.com/main/safetyapi/<API KEY>/<TICKET SITE>/<EMAIL CODIFICADO>

onde:

<COMANDO>Parâmetro que informa o método utilizado na consulta.
<API KEY>Chave de acesso vinculada a sua conta da SafetyMails.
<TICKET SITE>Chave de acesso vinculada a origem de consulta cadastrada.
<EMAIL CODIFICADO>O e-mail deve ser codificado utilizando o protocolo “base64”, caso contrário o sistema não receberá com perfeição os dados.

Exemplos de uso:

Exemplo de código em JavaScript

<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>

Exemplo de código em PHP

<?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;

Exemplos de mensagem de retorno da API de verificar emails

O retorno das consultas se dá no formato JSON, segundo a tabela abaixo:

Success:Retorno do tipo bool (true ou false), que informa se a chamada teve êxito.
DomainStatus:Status do domínio do e-mail consultado.
Status:Resultado da validação do e-mail, em caso de sucesso.
Email:Email consultado
Limited:Informa se o e-mail consultado é de um provedor limitado, ou seja, que recebe um número limitado de solicitações.
Public:Informa se o e-mail consultado é de domínio ‘Corporate’ (domínios privados e/ou que possuem regras privadas para recebimento) ou ‘Email provider’ (domínios que possuem regras públicas de recebimento).
Advice:Classificação sugerida pela SafetyMails para o status do e-mail consultado (Valid, Invalid, Risky ou Unknown).
Balance:Quantidade de créditos para consulta disponíveis em sua conta.
Msg:Retorna a mensagem de erro referente a falha na chamada (apenas quando a chamada apresenta erro).

Retorno em caso de sucesso na consulta

{
    "Success":true,
    "Email":"[email protected]",
    "Referer":"www.safetymails.com",
    "DomainStatus":"VALIDO",
    "Status":"VALIDO",
    "Advice":"Valid",
    "Public":null,
    "Limited":null,
    "Balance":4112343
}

Retorno em caso de erro na consulta

{
    "Success":false,
    "Email":"[email protected]",
    "Referer":"www.safetymails.com",
    "Status":"PENDENTE",
    "Advice":"Unknown",
    "Msg":"Referer inválido"
}

Mensagens de erro da API de verificar emails

Fique atento às seguintes mensagens de erro:

HTTPCodeErroDescrição
400Parâmetros inválidosChaves de acesso incorretas ou não existentes.
401API Key inválidaChaves de acesso incorretas ou não existentes.
406Ticket Origem inválido ou inativoVocê está tentando realizar consultas para uma origem API inativa. Vá ao seu painel e ative a origem corretamente.
403Origem diferente da cadastrada (%s)<>(%s):Você está tentando realizar consultas para uma origem API diferente da cadastrada em sua conta. Verifique a origem e tente novamente.
429Limite de consultas por hora ou minuto ou diário ultrapassado – Contacte o SuportePara proteger o seu formulário contra uso indevido, sua API permite somente um total de 20 consultas diárias oriundas de um mesmo IP (default). Para realizar mais consultas do que o previsto, entre em contato com o suporte ([email protected])
402Sem créditos para realizar a pesquisaSua conta não possui créditos para realizar a consulta. É preciso adquirir créditos.

Se precisar de mais orientações para customizar sua API de verificar emails, entre em contato com a nossa equipe de suporte ([email protected])

 

Outros conteúdos

Post navigation