É 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:
- Acesse sua conta na Safetymails (Se não tiver uma conta, crie agora mesmo e ganhe 100 créditos grátis);
- No menu superior, clique em “Real-time API“
- Selecione a opção “Para desenvolvedores“
- 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:
| HTTPCode | Erro | Descrição |
|---|---|---|
| 400 | Parâmetros inválidos | Chaves de acesso incorretas ou não existentes. |
| 401 | API Key inválida | Chaves de acesso incorretas ou não existentes. |
| 406 | Ticket Origem inválido ou inativo | Você está tentando realizar consultas para uma origem API inativa. Vá ao seu painel e ative a origem corretamente. |
| 403 | Origem 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. |
| 429 | Limite de consultas por hora ou minuto ou diário ultrapassado – Contacte o Suporte | Para 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]) |
| 402 | Sem créditos para realizar a pesquisa | Sua 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])