Central de Ajuda | Como customizar a API real-time

Como customizar a API real-time

Como criar uma API customizada para validar emails em formulários, apps ou webservices

Você pode customizar e instalar a API de verificação de emails da SafetyMails com total flexibilidade, usando a linguagem de programação que preferir. Com apenas algumas linhas de código e suas chaves de acesso, é possível integrar a verificação em tempo real diretamente em landing pages, formulários, aplicativos ou sistemas de ponto de venda (PDV).

A API responde instantaneamente às consultas, entregando os dados necessários para bloquear emails inválidos, reduzir fraudes e proteger seus cadastros desde o primeiro contato.

📌Nossa equipe está disponível para orientar na configuração do código. Basta clicar no link da agenda do suporte para falar com nossos especialistas.

1. Acesse sua conta e ative créditos

É necessário possuir uma assinatura de créditos ativa para utilizar a API de verificação de emails. Veja aqui os pacotes de verificação de emails disponíveis.

2. Acesse a API em tempo real

No menu superior da plataforma, clique em "Real-time API"

Clique na opção "Crie uma nova origem"

Em seguida, selecione "Para desenvolvedores"

3. Cadastre a origem da verificação

Dê um nome à origem e informe o domínio do seu formulário (ex: suaempresa.com).
Isso garante que a API só aceitará requisições de URLs autorizadas.

Após cadastrar a origem, o sistema gerará automaticamente os seguintes dados:

API Key
Ticket de Origem

Essas chaves serão usadas no seu código de integração com a API.

Exemplo de Ticket origem e API Key

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

Ticket Origem
b440e8d30f068************3d08b84afe2fe50

4. Autenticação via HMAC

Para garantir a segurança das requisições, é necessário autenticar as chamadas da API usando HMAC (Código de Autenticação de Mensagem baseado em hash). Esse mecanismo assegura que os dados não foram adulterados durante o tráfego, desde que tanto o emissor quanto o receptor compartilhem uma chave secreta.

A função de hash utilizada deve seguir o padrão HMAC-SHA256, combinando dois elementos:

VALOR: o email que será verificado

CHAVE: sua API Key fornecida pela plataforma

A fórmula de geração do hash é:

hash = HMAC_SHA256(VALOR, CHAVE);

Este hash deverá ser enviado no Header da requisição:

Sf-Hmac: (Conteúdo do Hash)

Exemplo

Sf-Hmac: afc5382171c3745890b56********************4aa43506326b4e1fc993cb

5. Sintaxe da consulta à API de verificação de emails

Para realizar chamadas à API de verificação em tempo real da SafetyMails, é necessário montar a URL corretamente e enviar o email via método POST. Veja como funciona:

Gere o código do ticket com o algoritmo SHA1:

CODE_TICKET = SHA1(<TICKET_ORIGEM>)

Monte a URL da requisição neste formato:

https://<TICKET_ORIGEM>.safetymails.com/api/<CODE_TICKET>

Envie a requisição com o campo email no corpo do POST.

📌 Importante: O email deve ser enviado com o nome do campo exatamente como "email", e a autenticação via Sf-Hmac deve estar presente no header.

7. Veja exemplos em diferentes linguagens

Exemplo de código JavaScript

<html>
<body>
<form action="">
<input type="email" name="email" value="">
<br>
<button type="button">OK</button>
</form>

<script>

// Esta função é apenas um exemplo, se preferir pode usar sua própria library javascript
async function sha1(text) {
const encoder = new TextEncoder();
const data = encoder.encode(text);
const hashBuffer = await crypto.subtle.digest("SHA-1", data);
return [...new Uint8Array(hashBuffer)]
.map(byte => byte.toString(16).padStart(2, "0"))
.join("");
}
// Esta função é apenas um exemplo, se preferir pode usar sua própria library javascript
async function hmacSHA256(value, key) {
const encoder = new TextEncoder();
const keyData = encoder.encode(key);
const valueData = encoder.encode(value);

const cryptoKey = await crypto.subtle.importKey(
"raw", keyData, { name: "HMAC", hash: { name: "SHA-256" } }, false, ["sign"]
);
const signature = await crypto.subtle.sign("HMAC", cryptoKey, valueData);
return [...new Uint8Array(signature)]
.map(byte => byte.toString(16).padStart(2, "0"))
.join("");
}

document.querySelector("button").addEventListener("click", async function () {
const emailInput = document.querySelector('[type="email"]');
if (!emailInput || emailInput.value.length < 1)
throw new Error("Invalid Email Input value");

// Insira abaixo os valores de ticket_origem e api_key gerados na plataforma da SafetyMails.
const ticket = '<TK ORIGEM INFORMADA NO PAINEL SAFETYMAILS>';
const api_key = '<APIKEY INFORMADA NO PAINEL SAFETYMAILS>';
const code = await sha1(ticket);

const email = emailInput.value;
const url = `https://${ticket}.safetymails.com/api/${code}`;
const hmac = await hmacSHA256(email, api_key);

let form = new FormData();
form.append('email',email);

try {
const response = await fetch(url, {
method: "POST",
headers: {
"Sf-Hmac": hmac
},
body: form
});

if (!response.ok) {
console.error(`HTTPCode ${response.status}`);
return;
}

const data = await response.json();

if (!data.Success) {
console.error("Response error", data);
return;
}

console.log("Response success", data);
} catch (error) {
console.error("Request failed", error);
}
});
</script>
</body>
</html>

Exemplo de código em PHP

<?php
function SafetyApi($email) {
$apiKey = '<APIKEY INFORMADA NO PAINEL SAFETYMAILS>';
$tkOrigem = '<TK ORIGEM INFORMADA NO PAINEL SAFETYMAILS>';
$timeout = 10; // Timeout da conexão com a Safetymails
$url = "https://{$tkOrigem}.safetymails.com/api/".sha1($tkOrigem);
$header[] = "Sf-Hmac: " . hash_hmac('sha256', $email, $apiKey);
$post['email'] = $email;

$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, $timeout);
curl_setopt($process, CURLOPT_ENCODING, '');
curl_setopt($process, CURLOPT_POST, 1);
curl_setopt($process, CURLOPT_HTTPHEADER, $header);
curl_setopt($process, CURLOPT_POSTFIELDS, http_build_query($post));

$ret = curl_exec($process);
curl_close($process);

$httpCode = curl_getinfo($process, CURLINFO_HTTP_CODE);

$result = NULL;

if ($ret === false && curl_errno($process) === CURLE_OPERATION_TIMEOUTED)
$httpCode = 408; // Timeout
elseif ($httpCode == 200)
$result = json_decode($ret, true);

# HTTPCODE 400 - Parâmetros inválidos
# HTTPCODE 401 - API Key inválida
# HTTPCODE 402 - Créditos insuficientes para a consulta
# HTTPCODE 403 - Acesso de uma origem diferente da cadastrada
# HTTPCODE 406 - Ticket Origem inválido ou inativo
# HTTPCODE 408 - Timeout
# HTTPCODE 429 - Limite de consultas por hora ou minuto ultrapassado

return ['Status'=>$httpCode, 'Result'=>$result];
}

$emailTeste = "teste@email.com";
print_r(SafetyApi($emailTeste));

Exemplo de código em Python

import requests
import hashlib
import hmac

def safety_api(email):
api_key = '<APIKEY INFORMADA NO PAINEL SAFETYMAILS>'
tk_origem = '<TK ORIGEM INFORMADA NO PAINEL SAFETYMAILS>'
timeout = 10 # Timeout da conexão com a Safetymails

url = f"https://{tk_origem}.safetymails.com/api/{hashlib.sha1(tk_origem.encode()).hexdigest()}"

sf_hmac = hmac.new(api_key.encode(), email.encode(), hashlib.sha256).hexdigest()
headers = {"Sf-Hmac": sf_hmac}
data = {"email": email}

try:
response = requests.post(url, headers=headers, data=data, timeout=timeout)
http_code = response.status_code
result = response.json() if http_code == 200 else None
except requests.exceptions.RequestException as e:
return {"Status": "400", "Result": str(e)}

return {"Status": http_code, "Result": result}

# Exemplo de uso
if __name__ == "__main__":
email_teste = "teste@email.com"
resposta = safety_api(email_teste)
print(resposta)

Exemplo de código em Java

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SafetyApi {
public static String generateSha1(String input) throws Exception {
MessageDigest md = MessageDigest.getInstance("SHA-1");
byte[] hash = md.digest(input.getBytes(StandardCharsets.UTF_8));
StringBuilder hexString = new StringBuilder();
for (byte b : hash) {
hexString.append(String.format("%02x", b));
}
return hexString.toString();
}

public static String generateHmacSha256(String key, String data) throws Exception {
Mac hmac = Mac.getInstance("HmacSHA256");
SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
hmac.init(secretKey);
byte[] hash = hmac.doFinal(data.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(hash);
}

public static String safetyApi(String email) {
String apiKey = "<APIKEY INFORMADA NO PAINEL SAFETYMAILS>";
String tkOrigem = "<TK ORIGEM INFORMADA NO PAINEL SAFETYMAILS>";
int timeout = 10000; // Timeout em milissegundos

try {
String sha1TkOrigem = generateSha1(tkOrigem);
String urlStr = "https://" + tkOrigem + ".safetymails.com/api/" + sha1TkOrigem;
String sfHmac = generateHmacSha256(apiKey, email);

URL url = new URL(urlStr);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setRequestProperty("Sf-Hmac", sfHmac);
conn.setDoOutput(true);
conn.setConnectTimeout(timeout);
conn.setReadTimeout(timeout);

String postData = "email=" + email;
try (OutputStream os = conn.getOutputStream()) {
os.write(postData.getBytes(StandardCharsets.UTF_8));
}

int responseCode = conn.getResponseCode();
StringBuilder response = new StringBuilder();

try (BufferedReader br = new BufferedReader(new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
String line;
while ((line = br.readLine()) != null) {
response.append(line);
}
}

return "{ \"Status\": " + responseCode + ", \"Result\": " + response.toString() + " }";
} catch (Exception e) {
return "{ \"Status\": \"Erro\", \"Result\": \"" + e.getMessage() + "\" }";
}
}

public static void main(String[] args) {
String emailTeste = "teste@email.com";
System.out.println(safetyApi(emailTeste));
}
}

Exemplo de código em Go

package main

import (
"crypto/hmac"
"crypto/sha1"
"crypto/sha256"
"encoding/hex"
"fmt"
"io/ioutil"
"net/http"
"net/url"
"strings"
"time"
)

const (
apiKey = "<APIKEY INFORMADA NO PAINEL SAFETYMAILS>"
tkOrigem = "<TK ORIGEM INFORMADA NO PAINEL SAFETYMAILS>"
timeout = 10 * time.Second // Timeout da conexão
)

// Função para gerar SHA1
func generateSHA1(input string) string {
h := sha1.New()
h.Write([]byte(input))
return hex.EncodeToString(h.Sum(nil))
}

// Função para gerar HMAC-SHA256
func generateHMACSHA256(key, data string) string {
h := hmac.New(sha256.New, []byte(key))
h.Write([]byte(data))
return hex.EncodeToString(h.Sum(nil))
}

// Função que faz a requisição para a API
func safetyAPI(email string) (map[string]interface{}, error) {
urlStr := fmt.Sprintf("https://%s.safetymails.com/api/%s", tkOrigem, generateSHA1(tkOrigem))
hmacSignature := generateHMACSHA256(apiKey, email)

// Criando os dados no formato form-data
formData := url.Values{}
formData.Set("email", email)
formEncoded := formData.Encode() // "email=teste@email.com"

// Criando a requisição POST
client := http.Client{Timeout: timeout}
req, err := http.NewRequest("POST", urlStr, strings.NewReader(formEncoded))
if err != nil {
return nil, err
}

// Definindo os cabeçalhos
req.Header.Set("Sf-Hmac", hmacSignature)
req.Header.Set("Content-Type", "application/x-www-form-urlencoded") // Envio como form-data

// Enviando a requisição
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()

// Lendo resposta
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
return nil, err
}

// Criando o retorno
result := map[string]interface{}{
"Status": resp.StatusCode,
"Result": string(body), // Retorna o JSON da API como string
}

return result, nil
}

func main() {
email := "teste@email.com"
resposta, err := safetyAPI(email)
if err != nil {
fmt.Println("Erro:", err)
} else {
fmt.Println(resposta)
}
}

8. Estrutura e significado das respostas da API

Após cada requisição, a API da SafetyMails retorna uma resposta no formato JSON, que informa se a verificação foi bem-sucedida, qual o status do email consultado e quantos créditos ainda estão disponíveis na conta.

Essas informações são essenciais para identificar rapidamente se o email é válido, inválido, arriscado ou desconhecido, além de apontar possíveis problemas técnicos ou operacionais.

Confira abaixo os principais campos retornados pela API:

Campo	O que significa
Success	Retorno do tipo bool (true ou false). Indica se a requisição foi executada com sucesso. Se retornar false, significa que a consulta não foi realizada, podendo haver falhas como: chave de API incorreta, ticket inválido ou inativo, parâmetros malformados, limite de requisições excedido ou falta de créditos.
DomainStatus	Status do domínio do e-mail consultado.
Status	Resultado da validação do e-mail, em caso de sucesso. Os status podem ser: Válidos, Role-based, baixa entregabilidade, descartável, incertos, junk, inválidos, domínio inválido, erro de sintaxe e pendentes.
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	É uma classificação sugerida pela SafetyMails para o status do e-mail consultado (Valid, Invalid, Risky ou Unknown) para facilitar a análise.
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).

Exemplo de retorno bem-sucedido

Retorno em JSON

{
"Success":true,
"Email":"testeemail@safetymails.com",
"Referer":"www.safetymails.com",
"DomainStatus":"VALIDO",
"Status":"VALIDO",
"Advice":"Valid",
"Public":null,
"Limited":null,
"Balance":4112343
}

Exemplo em caso de erro na consulta

Retorno em JSON

{
"Success":false,
"Email":"testeemail@safetymails.com",
"Referer":"www.safetymails.com",
"Status":"PENDENTE",
"Advice":"Unknown",
"Msg":"Referer inválido"
}

9. Mensagens de erro retornadas pela API de verificação de emails

As mensagens de erro abaixo só serão exibidas quando o campo Success for false na resposta da API. Nestes casos, a consulta não foi realizada com sucesso, e o campo Msg informará o motivo da falha.

Esses erros geralmente estão relacionados a problemas de autenticação, parâmetros incorretos, falta de créditos ou limites excedidos.

HTTP Code	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	A Safetymails oferece uma proteção ao seu formulário de uso indevido, permitindo que você limite as consultas vindas de um mesmo IP, além disso todos os planos possuem limites de consultas por hora e minuto, protegendo de erros que possam gerar loop. Para realizar mais consultas do que o previsto, entre em contato com o suporte (support@safetymails.com)
402	Sem créditos para realizar a pesquisa	Sua conta não possui créditos para realizar a consulta. É preciso adquirir créditos.

📌 Dica: Sempre verifique o campo Msg no retorno JSON para entender o motivo exato da falha.

Se precisar de mais orientações para configurar sua API, fale com nosso time de suporte:
📧 support@safetymails.com

Ainda precisa de ajuda? Envie-nos uma Mensagem