Início › Guias

Monitoramento de blacklist: scripts, API e alertas por webhook

Publicado em 2026-11-03 ／ Atualizado em 2026-11-03 ／ Por Yuki Nakazawa

Monitorar blacklists significa consultar periodicamente várias listas de bloqueio DNS (DNSBLs) para os seus IPs e domínios de envio e gerar um alerta apenas quando um resultado mudar. Detectar uma listagem no momento em que ela acontece, e não quando os clientes reclamam de e-mails devolvidos, dá tempo para encontrar a causa e pedir a remoção antes que o estrago se espalhe.

Há duas formas práticas de fazer isso: rodar você mesmo um pequeno script com dig e cron, ou entregar as verificações a um serviço por meio de uma API e webhooks. Em qualquer caso, dois detalhes decidem se o monitor diz a verdade: consultas enviadas por resolvedores públicos são recusadas por listas como o Spamhaus e produzem respostas enganosas, e códigos de erro nunca devem ser contados como listagens.

As regras dos operadores de listas citadas aqui se baseiam nas páginas oficiais deles em 11/2026. As políticas mudam, então confirme-as antes de confiar em uma configuração. Para entender como as DNSBLs funcionam, veja o que é uma DNSBL (RBL).

Defina o que monitorar e quais listas consultar

Comece anotando os itens que você realmente precisa monitorar.

• Endereços IP de envio. São os endereços de onde o seu servidor de e-mail ou o seu provedor de e-mail realmente envia. O seu site e os seus e-mails muitas vezes saem de máquinas diferentes, então confirme o endereço nos cabeçalhos Received de uma mensagem que você enviou. Se você envia por IPv6, monitore esses endereços também.
• Domínios. O domínio do seu endereço From e quaisquer domínios que apareçam em links dentro das suas mensagens. Os domínios são verificados em listas de bloqueio de domínios, que são separadas das listas de IP.

O formato da consulta é definido na RFC 5782. Para IPv4, você inverte os octetos e acrescenta a zona da lista, então 192.0.2.99 em uma lista vira 99.2.0.192 seguido do nome da zona. Para IPv6, o endereço é escrito como 32 nibbles hexadecimais em ordem inversa. Um domínio é simplesmente colocado antes da zona. Uma entrada listada retorna um registro A, por convenção em 127.0.0.0/8; uma não listada retorna NXDOMAIN. A RFC também observa que as listas devem publicar um registro TXT explicando o motivo da listagem.

Monitore várias listas, e não só uma, porque nem todos os destinatários usam as mesmas. O significado de cada código de retorno varia conforme o operador; o nosso guia de códigos de retorno de DNSBL cobre os mais comuns.

Por que resolvedores públicos dão respostas erradas

Um erro comum em monitoramentos caseiros é enviar as consultas por um resolvedor público como o Google Public DNS (8.8.8.8) ou o Cloudflare (1.1.1.1). O FAQ oficial de uso de DNSBL do Spamhaus explica o que acontece:

• O uso gratuito das DNSBLs do Spamhaus exige que o uso seja não comercial e que as consultas não venham de um resolvedor público ou aberto, nem de um IP com DNS reverso genérico.
• Por resolvedores abertos gratuitos como o Google Public DNS, as consultas vão, na maioria dos casos, receber uma resposta de não listado (NXDOMAIN). Em outras palavras, um IP listado pode parecer limpo.
• Consultas por um resolvedor público também podem receber 127.255.255.254. Isso é um código de erro, não uma listagem. Da mesma forma, 127.255.255.252 indica um erro de digitação no nome da DNSBL, e 127.255.255.255 indica um número excessivo de consultas. O Spamhaus afirma que esses códigos não devem ser entendidos como indicação de que o objeto consultado está listado.
• Resolvedores que reescrevem respostas NXDOMAIN retornam um endereço IP no lugar, então você nunca vê o NXDOMAIN correto.

A principal recomendação do FAQ é usar o seu próprio resolvedor DNS. Para quem precisa continuar em um resolvedor público, o Spamhaus indica o seu Data Query Service (DQS); confira os termos para saber o que é gratuito. O FAQ sugere dig txt whoami.fastly.net para ver qual resolvedor você está de fato usando.

A RFC 5782 acrescenta uma verificação de sanidade embutida: uma lista IPv4 precisa conter uma entrada para 127.0.0.2 e não pode conter 127.0.0.1, e os clientes devem verificar essas entradas de teste periodicamente para confirmar que a lista está funcionando. No exemplo do Spamhaus, 2.0.0.127.zen.spamhaus.org retorna 127.0.0.10, 127.0.0.4 e 127.0.0.2, enquanto 1.0.0.127.zen.spamhaus.org retorna NXDOMAIN. Um monitor deve testar isso primeiro e descartar a execução se o teste falhar.

Opção 1: um script com dig e cron

Aqui está um script mínimo que verifica um endereço IPv4 no Spamhaus ZEN e no SpamCop (bl.spamcop.net, que segundo a documentação do SpamCop responde 127.0.0.2 para um IP listado). Substitua o endereço e as zonas pelos seus.

#!/bin/sh
# Query your own recursive resolver (e.g. unbound on the same host), never a public one
RESOLVER=127.0.0.1
IP=192.0.2.10
ZONES="zen.spamhaus.org bl.spamcop.net"
REV=$(echo "$IP" | awk -F. '{print $4"."$3"."$2"."$1}')

q() {
  out=$(dig +time=3 +tries=1 @"$RESOLVER" "$1" A) || { echo ERR; return; }
  case "$out" in
    *"status: NOERROR"*) a=$(printf '%s\n' "$out" | awk '$4=="A"{print $5}'); echo "${a:-NX}" ;;
    *"status: NXDOMAIN"*) echo NX ;;
    *) echo ERR ;;
  esac
}

for Z in $ZONES; do
  # If the 127.0.0.2 test entry does not resolve to a listing code, do not trust this run
  case "$(q "2.0.0.127.$Z")" in
    127.255.255.*|NX|ERR) echo "$Z ERROR test-entry"; continue ;;
    127.*) ;;
    *) echo "$Z ERROR test-entry"; continue ;;
  esac
  A=$(q "$REV.$Z")
  case "$A" in
    NX)            echo "$Z CLEAN" ;;
    ERR)           echo "$Z ERROR no-answer" ;;
    127.255.255.*) echo "$Z ERROR $A" ;;
    127.*)         echo "$Z LISTED $A" ;;
    *)             echo "$Z ERROR unexpected $A" ;;
  esac
done

O que o script faz:

• Só o status NXDOMAIN conta como limpo, 127.255.255.x é erro e qualquer outro 127.x é listagem. Tudo o que estiver fora de 127.0.0.0/8 é tratado como anomalia, como um resolvedor que reescreve respostas.
• Um timeout faz o dig sair com código diferente de zero, enquanto SERVFAIL e REFUSED saem com 0. Nenhum deles é tratado como limpo; o script registra um erro.
• Os códigos de retorno são específicos de cada lista. Algumas listas usam 127.0.0.1 para indicar que uma consulta foi recusada, por exemplo, então leia a documentação de cada lista que você adicionar e amplie o bloco case quando necessário.

Depois, deixe o cron comparar cada execução com a anterior e enviar e-mail somente quando algo mudar:

# Example: run hourly, send mail only when the output differs from the last run
0 * * * * /usr/local/bin/dnsbl-watch.sh > /var/tmp/dnsbl.now 2>&1; cmp -s /var/tmp/dnsbl.now /var/tmp/dnsbl.prev || mail -s "DNSBL status changed" you@example.com < /var/tmp/dnsbl.now; mv /var/tmp/dnsbl.now /var/tmp/dnsbl.prev

O intervalo de uma hora é só um exemplo. O Spamhaus oferece acesso gratuito para uso não comercial de baixo volume, e clientes que ultrapassam o seu limite de volume de consultas precisam de uma opção paga; confira os termos de cada lista à medida que o número de IPs monitorados crescer. O FAQ também recomenda executar os comandos algumas vezes para confirmar que os resultados se mantêm.

Opção 2: a API em lote do DNSBL Checker e webhooks

Se você prefere não manter um resolvedor e regras de interpretação para cada lista, pode deixar um serviço fazer as verificações. Abaixo está a API v1 deste site, limitada ao que a implementação do servidor de fato faz. A referência fica em /en/api-docs, e as chaves são emitidas na página de membros em /account. O cadastro pede apenas um endereço de e-mail, e o login é feito por um link enviado por e-mail.

Autenticação e limites

• As chaves começam com dnsbl_ e são exibidas uma única vez, logo após a emissão; só um hash é armazenado. Emitir uma nova chave invalida a anterior.
• Envie a chave no cabeçalho X-API-Key em todas as requisições. Somente HTTPS; o http:// simples é redirecionado para https://, então chame https:// desde o início.
• Os limites são 1.000 verificações por dia (cada alvo conta como uma), 100 alvos por lote e 50 monitores cadastrados. Acima do limite diário, você recebe 429 com daily_limit_exceeded e um horário em resets_at.

Verificações em lote

Envie um array targets com nomes de domínio ou endereços IP para POST /api/v1/batch:

curl -X POST https://dnsblchecker.com/api/v1/batch \
  -H "X-API-Key: $DNSBL_API_KEY" -H "Content-Type: application/json" \
  -d '{"targets":["example.com"]}'

Se algum alvo ainda precisar ser verificado, a resposta é 202 com um batch_id. Consulte GET /api/v1/batch/{batch_id} a cada poucos segundos até que status seja done (exemplo resumido; os números e o nome da lista são ilustrativos, não um resultado real):

{
  "batch_id": 1, "status": "done", "created": "2026-11-03 09:10:41", "count": 1, "pending": 0,
  "results": [
    {
      "target": "example.com", "type": "domain",
      "status": "done", "verdict": "listed",
      "checked_at": "2026-11-03 09:12",
      "lists_checked": 80, "listed_count": 1, "error_count": 4,
      "listed_on": [
        { "list": "ZapBL RHSBL", "zone": "rhsbl.zapbl.net", "response": "127.0.0.2" }
      ]
    }
  ]
}

• verdict é listed se pelo menos uma lista informar uma listagem; caso contrário, clean. Listas que deram timeout ou responderam com um código de erro como 127.255.255.x são contadas em error_count e nunca como listagens.
• Um lote retorna um resultado armazenado se houver um dos últimos 30 dias. Para monitoramento agendado, sempre olhe checked_at.
• Alvos malformados voltam em rejected com um motivo e não são contados. Se você passar uma URL, só o nome do host é usado. Faixas reservadas para documentação, como 192.0.2.0/24, são rejeitadas, então teste com um IP de envio real.

Monitoramento por webhook

Cadastre um target e uma callback_url com POST /api/v1/monitors. Cada alvo cadastrado passa então a ser verificado uma vez por dia sem usar o cache (a primeira verificação ocorre em cerca de um dia após o cadastro), e um POST em JSON é enviado para a sua URL apenas na primeira verificação (monitor.initial) e quando o veredito muda entre listado e limpo (monitor.status_changed).

curl -X POST https://dnsblchecker.com/api/v1/monitors \
  -H "X-API-Key: $DNSBL_API_KEY" -H "Content-Type: application/json" \
  -d '{"target":"example.com","callback_url":"https://your-app.example/hooks/dnsbl"}'

• O signing_secret da resposta é exibido uma única vez. Cada entrega traz um cabeçalho X-DNSBL-Signature: sha256=..., o HMAC-SHA256 do corpo bruto com esse segredo como chave. Verifique-o do seu lado.
• A callback_url precisa ser https na porta 443 e resolver para um IP público; redirecionamentos não são seguidos e o timeout é de 10 segundos, então coloque o trabalho pesado em fila e responda rápido.
• Se o seu endpoint retornar algo diferente de 2xx, ou se a conexão falhar, a entrega é tentada novamente na próxima verificação diária. O motivo aparece como last_delivery_error em GET /api/v1/monitors, e DELETE /api/v1/monitors/{monitor_id} remove um monitor.

import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, request.headers.get("X-DNSBL-Signature", ""))

Como desenhar os alertas: frequência, várias listas e alarmes falsos

Um monitor só é útil se as pessoas ainda lerem os alertas dele depois de alguns meses. Um que dispara o tempo todo logo passa a ser ignorado.

Frequência

• Separe a frequência das consultas da frequência das notificações. Consulte em intervalos programados, mas notifique só quando o estado mudar. Uma mensagem diária de "tudo limpo" esconde o único alerta que importa.
• A RFC 5782 diz que os TTLs das listas devem refletir a rapidez com que a lista muda, e que listas de fontes de spam podem usar TTLs de minutos. Escolha o seu intervalo sabendo que algumas listagens aparecem e expiram rapidamente.
• Consultas em excesso podem violar os termos de uso de uma lista ou render a você 127.255.255.255 (consultas excessivas) em vez de respostas reais.

Várias listas

• Inclua o nome da lista em cada alerta. As listas diferem na quantidade de destinatários que as usam, então você pode alertar imediatamente para as listas que mais importam para os seus destinatários e agrupar o restante em um resumo.
• O webhook acima só dispara quando o veredito muda entre listado e limpo. Se um alvo já está listado e depois aparece em uma segunda lista, nenhum evento é enviado. Acompanhe last_listed_count em GET /api/v1/monitors, ou rode um lote e leia listed_on, para pegar esse caso.

Falsos positivos e respostas passageiras

• Registre os erros separadamente das listagens. O Spamhaus alerta os operadores para não rejeitar nem filtrar e-mails com base nos seus códigos de erro; a mesma lógica vale para o monitoramento. Um timeout ou uma resposta 127.255.255.x nunca deve disparar um alerta de listagem.
• Para não reagir a um único resultado estranho, alerte só depois de dois resultados idênticos consecutivos, ou consulte novamente alguns minutos depois antes de enviar qualquer coisa.
• Se os erros persistirem, suspeite de uma mudança de resolvedor ou de uma mudança do lado da lista, e olhe primeiro o resultado da entrada de teste.
• Um IP residencial na Spamhaus PBL é uma listagem por política, não uma acusação: significa que o endereço não deve enviar e-mails diretamente. Decida, lista por lista, o que conta como alerta (veja remoção do Spamhaus).

O que fazer quando uma listagem é detectada

1. Confirme. Verifique a página de consulta do próprio operador e anote o nome da lista, o horário e qualquer motivo exibido.
2. Corrija a causa primeiro. Procure contas comprometidas, formulários web abusados, máquinas infectadas, má higiene de listas e DNS reverso (PTR) ou nomes HELO que não correspondem. Pedir a remoção enquanto a causa persiste geralmente leva a uma nova listagem.
3. Siga o processo de remoção daquela lista. A decisão de remover da lista é de cada operador, e enviar um pedido não garante que a listagem será retirada. Se você não controla o IP, como na hospedagem compartilhada, fale com o seu provedor de hospedagem ou de acesso.
4. Deixe o monitor confirmar o resultado. Os destinatários também usam filtros próprios, então acompanhe a entrega depois que o veredito voltar a limpo.

Para uma consulta pontual de um IP ou domínio, use o verificador de blacklist. Se rastrear a causa ou cuidar dos pedidos for mais do que você consegue assumir, você pode pedir a nossa ajuda. Para o caminho completo de solução de problemas quando os e-mails estão voltando, veja e-mails bloqueados por blacklists.

Perguntas frequentes

Páginas oficiais consultadas

As informações deste artigo foram conferidas nas páginas oficiais abaixo na data da publicação. Políticas e procedimentos mudam sem aviso prévio; consulte as páginas oficiais antes de tomar qualquer decisão importante.

• RFC 5782: DNS Blacklists and Whitelists
• Spamhaus FAQ: DNSBL Usage
• Spamhaus: Using our public mirrors? Check your return codes now
• SpamCop FAQ: How do I configure my mailserver to reject mail based on the blocklist?

Guias relacionados

Todos os guias →