Verify

Verificar um e-mail

POST/v1/verify

Síncrono: a resposta já traz o resultado, normalmente em poucos segundos.

curl -X POST https://gateway.autentify.com.br/v1/verify \
  -H "Authorization: Bearer $AUTENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@empresa.com.br"}'

{
  "id": "vr_5f2c9a81d04e7b36a1c8e2f4",
  "email": "ana@empresa.com.br",
  "domain": "empresa.com.br",
  "verified_at": "2026-10-03T14:02:11.482913Z",
  "state": "deliverable",
  "reason": "accepted_email",
  "attributes": {
    "free": false,
    "role": false
  }
}

Resultado

Estados

Motivos

Um undeliverable pode vir sem reason. Motivos novos podem ser acrescentados: trate um código desconhecido sem falhar e decida pelo state.

Atributos

Erros deste módulo

Além dos erros comuns: 422 invalid_email quando o endereço não tem formato de e-mail (nada é cobrado). Falhas temporárias chegam como 503 provider_error, 503 service_unavailable ou 503 provider_timeout, sempre sem cobrança.

Lotes

Para listas, crie um lote de até 5.000 entradas. O lote é processado em segundo plano: você recebe o identificador na hora e consulta o andamento.

1. Criar o lote

POST/v1/verify/batches

curl -X POST https://gateway.autentify.com.br/v1/verify/batches \
  -H "Authorization: Bearer $AUTENTIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["ana@empresa.com.br","sem-arroba","joao@gmail.com","joao@gmail.com"]}'

{
  "id": "vb_0b7d41c9e83a52f6d1907ce4",
  "status": "queued",
  "created_at": "2026-10-03T14:05:40.120394Z",
  "finished_at": null,
  "counts": {
    "entries": 4,
    "unique": 2,
    "invalid": 1,
    "duplicates": 1,
    "processed": 0,
    "failed": 0
  },
  "progress": 0,
  "credits": {
    "reserved": 2,
    "charged": 0
  }
}

• Endereços repetidos são verificados e cobrados uma vez só.
• Entradas sem formato de e-mail não são verificadas nem cobradas.
• A criação reserva 1 crédito por endereço único (credits.reserved). No fim, só os resultados conclusivos são cobrados (credits.charged) e o restante volta para o saldo.
• Sem saldo para o lote inteiro, a resposta é 402 insufficient_credits e nada é criado.
• Envie Idempotency-Key para não criar o mesmo lote duas vezes.

2. Acompanhar

GET/v1/verify/batches/{id}

Devolve o mesmo objeto da criação, atualizado. Consulte a cada 5 a 10 segundos até o estado final.

3. Buscar os resultados

GET/v1/verify/batches/{id}/results?cursor=0&limit=500

Uma linha por entrada enviada, na mesma ordem. Pode ser consultado durante o processamento. limit vai de 1 a 1.000 (padrão 500). Para a próxima página, envie em cursor o valor de next_cursor; quando ele vier null, acabou.

{
  "results": [
    {
      "position": 0,
      "input": "ana@empresa.com.br",
      "result": {
        "id": "vr_5f2c9a81d04e7b36a1c8e2f4",
        "email": "ana@empresa.com.br",
        "domain": "empresa.com.br",
        "verified_at": "2026-10-03T14:02:11.482913Z",
        "state": "deliverable",
        "reason": "accepted_email",
        "attributes": {
          "free": false,
          "role": false
        }
      }
    },
    {
      "position": 1,
      "input": "sem-arroba",
      "error": {
        "code": "invalid_email",
        "message": "Endereço de e-mail inválido."
      }
    },
    {
      "position": 2,
      "input": "joao@gmail.com",
      "status": "pending"
    }
  ],
  "next_cursor": 3
}

Cada linha traz a posição, o texto enviado e uma destas três coisas:

• result: o resultado, no mesmo formato da verificação unitária. Entradas repetidas trazem o mesmo resultado.
• error: a entrada era inválida (invalid_email) ou a verificação falhou. Sem cobrança.
• status: "pending": ainda não processada.