Formato de Resposta

Todas as respostas da API FlowMail seguem uma estrutura JSON consistente. Esta página detalha cada campo, seus tipos e valores possíveis para facilitar a integração.

Estrutura Completa

A resposta de uma verificação (única ou cada item do lote) segue esta estrutura:

JSON — Estrutura completa

{
  "email": "usuario@exemplo.com",
  "verdict": "deliverable",
  "score": 95,
  "checks": {
    "syntax": true,
    "mx_records": true,
    "smtp_valid": true,
    "deliverable": true
  },
  "details": {
    "domain": "exemplo.com",
    "username": "usuario",
    "free": false,
    "disposable": false,
    "role_account": false,
    "catch_all": false,
    "mx_host": "mx1.exemplo.com",
    "suggestion": null
  },
  "meta": {
    "cached": false,
    "latency_ms": 287,
    "verified_at": "2026-03-01T14:30:00Z"
  }
}

Campos Raiz

Campo	Tipo	Descrição
`email`	string	O endereço de email verificado, normalizado para minúsculas.
`verdict`	string	Veredito final da verificação. Valores possíveis: `deliverable`, `undeliverable`, `risky`, `unknown`.
`score`	integer	Pontuação de confiabilidade de 0 (certamente inválido) a 100 (certamente válido).
`checks`	object	Resultado individual de cada verificação técnica realizada.
`details`	object	Informações detalhadas sobre o domínio e o endereço de email.
`meta`	object	Metadados da verificação (cache, latência, timestamp).

Objeto `checks`

O objeto checks contém o resultado de cada verificação técnica, todas com valores booleanos. A verificação ocorre em cascata: se um passo falha, os seguintes são marcados como false.

Campo	Tipo	Descrição
`syntax`	boolean	O email possui formato válido de acordo com a RFC 5322. Verifica caracteres, estrutura usuario@dominio e TLD.
`mx_records`	boolean	O domínio possui registros MX (Mail Exchange) configurados no DNS, indicando que pode receber emails.
`smtp_valid`	boolean	O servidor SMTP respondeu corretamente durante a conexão de verificação.
`deliverable`	boolean	O servidor SMTP aceitou a entrega para este endereço específico (RCPT TO retornou sucesso).

Exemplo: todas as verificações positivas

"checks": {
  "syntax": true,
  "mx_records": true,
  "smtp_valid": true,
  "deliverable": true
}

Exemplo: falha na verificação MX (cascata)

"checks": {
  "syntax": true,
  "mx_records": false,
  "smtp_valid": false,
  "deliverable": false
}

Objeto `details`

O objeto details fornece informações enriquecidas sobre o domínio e o endereço de email.

Campo	Tipo	Descrição
`domain`	string	O domínio do endereço de email (parte após o @).
`username`	string	O nome de usuário do endereço (parte antes do @).
`free`	boolean	Indica se o domínio é de um provedor de email gratuito (Gmail, Yahoo, Outlook, etc.).
`disposable`	boolean	Indica se o domínio pertence a um serviço de email temporário/descartável (Mailinator, Guerrilla Mail, etc.). Base de dados com mais de 100.000 domínios.
`role_account`	boolean	Indica se o endereço é uma conta de função (ex: info@, admin@, noreply@, contato@). Esses endereços geralmente não pertencem a uma pessoa específica.
`catch_all`	boolean	Indica se o domínio aceita emails para qualquer endereço (catch-all). Nesse caso, a verificação SMTP não consegue confirmar se o endereço específico existe.
`mx_host`	string\|null	O hostname do servidor MX de maior prioridade do domínio. Retorna `null` se nenhum registro MX foi encontrado.
`suggestion`	string\|null	Sugestão de correção quando um possível erro de digitação é detectado (ex: "gmial.com" sugere "gmail.com"). Retorna `null` se nenhuma correção for identificada.

Exemplo: email com sugestão de correção

"details": {
  "domain": "gmial.com",
  "username": "joao",
  "free": false,
  "disposable": false,
  "role_account": false,
  "catch_all": false,
  "mx_host": null,
  "suggestion": "gmail.com"
}

Objeto `meta`

O objeto meta contém metadados da verificação, úteis para diagnóstico e auditoria.

Campo	Tipo	Descrição
`cached`	boolean	Se `true`, o resultado foi obtido do cache (verificação anterior recente). Se `false`, a verificação foi feita em tempo real. Resultados em cache têm latência significativamente menor.
`latency_ms`	integer	Tempo total de processamento da verificação em milissegundos. Resultados em cache tipicamente retornam em menos de 5ms. Verificações em tempo real variam entre 200ms e 3000ms.
`verified_at`	string	Data e hora da verificação no formato ISO 8601 (UTC). Quando o resultado vem do cache, este campo reflete a data da verificação original.

Vereditos e Ranges de Score

O veredito é determinado automaticamente com base no score e nas verificações realizadas. A tabela abaixo resume cada veredito com seu range de score e a ação recomendada.

Veredito	Score	Significado	Ação Recomendada
deliverable	80 – 100	O email existe, o domínio possui MX válido e o servidor aceitou a entrega.	Seguro para envio
risky	20 – 70	O email pode existir, mas apresenta sinais de risco: descartável, catch-all ou role account.	Enviar com cautela
unknown	30 – 50	Não foi possível determinar. O servidor pode estar temporariamente fora do ar ou bloqueando verificações.	Tentar novamente mais tarde
undeliverable	0 – 20	O email não existe, o domínio não tem MX ou o servidor rejeitou a entrega explicitamente.	Não enviar

Dicas de Integração

Use o score, não apenas o veredito. Defina um threshold personalizado para o seu caso de uso. Por exemplo, aceite apenas emails com score acima de 70 no cadastro, mas permita score 40+ para newsletters.

Aproveite o campo suggestion. Quando não for null, exiba a sugestão ao usuário: "Você quis dizer joao@gmail.com?"

Monitore o campo cached. Resultados em cache são gratuitos e instantâneos. Se sua taxa de cache for baixa, considere cachear os resultados do seu lado também.

Filtre role accounts e descartáveis. Use os campos role_account e disposable para bloquear cadastros de baixa qualidade, mesmo quando o veredito é deliverable.