Como customizar a API de verificar emails para formulários

É 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

Checa HMAC

Um HMAC (Código de Autenticação de Mensagem) baseado em hash pode ser usado para determinar se uma mensagem enviada por um canal inseguro foi adulterada, desde que o remetente e o receptor compartilhem uma chave secreta.

Para gerar o hash será necessário utilizar uma função criptografando o valor no padrão HMAC-SHA256, onde será informado o valor em texto e uma chave para acesso.

A formula para o hash abaixo:

hash = HMAC_SHA256(VALOR, CHAVE);

VALOR = EMAIL
CHAVE = API_KEY

Checa Hash da Página

Ao habilitar esta função na configuração da sua origem um campo de texto irá aparecer, onde é possível cadastrar um hash único que será verificado na consulta.

Ao habilitar será necessário enviar um hash (SHA1) que deverá coincidir com o hash único que foi cadastrado na criação de sua origem no sistema.

Este hash pode ser qualquer valor da sua página criptografado, tal como a URL da página da consulta, por exemplo.

Sintaxe de consulta

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

CODE_TICKET = SHA1 ()

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

Exemplos de uso:

Exemplo de código em 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));

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

	$httpCode = curl_getinfo($process, CURLINFO_HTTP_CODE);

	if ($httpCode == 200)
		$result = json_decode($result, 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 429 - Limite de consultas por hora ou minuto ultrapassado

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

$emailTeste = "[email protected]";
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 = "[email protected]"
    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 = "[email protected]";
        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 protected]"

	// 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 := "[email protected]"
	resposta, err := safetyAPI(email)
	if err != nil {
		fmt.Println("Erro:", err)
	} else {
		fmt.Println(resposta)
	}
}

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	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 ([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])

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

Cadastrando uma origem para a API de verificar emails:

Exemplo de Ticket origem e API Key

Checa HMAC

Checa Hash da Página

Sintaxe de consulta

Exemplos de uso:

Exemplo de código em JavaScript

Exemplo de código em PHP

Exemplo de código em Python

Exemplo de código em Java

Exemplo de código em Go

Exemplos de mensagem de retorno da API de verificar emails

Retorno em caso de sucesso na consulta

Retorno em caso de erro na consulta

Mensagens de erro da API de verificar emails

Outros conteúdos

Política de Proteção de Dados

Como verificar listas de emails na Mailchimp

Docs & Helpdesk

Cadastrando uma origem para a API de verificar emails:

Exemplo de Ticket origem e API Key

Checa HMAC

Checa Hash da Página

Sintaxe de consulta

Exemplos de uso:

Exemplo de código em JavaScript

Exemplo de código em PHP

Exemplo de código em Python

Exemplo de código em Java

Exemplo de código em Go

Exemplos de mensagem de retorno da API de verificar emails

Retorno em caso de sucesso na consulta

Retorno em caso de erro na consulta

Mensagens de erro da API de verificar emails

Outros conteúdos

Post navigation