GET /check

Valida a configuração DNS (DKIM, SPF e DMARC) dos domínios remetentes e retorna o resultado em JSON.

Endpoints

Método	Caminho	Descrição
GET	`/check`	Valida todos os domínios configurados.
GET	`/check/{dominio}`	Valida apenas o domínio especificado. Retorna 404 se o domínio não estiver configurado.

Autenticação

O endpoint usa o mesmo mecanismo do POST /send: header X-Auth-Token comparado em tempo constante com MXOUT_AUTH_TOKEN.

X-Auth-Token: {TOKEN}

Se o token estiver ausente ou incorreto, a resposta é 401. Se MXOUT_AUTH_TOKEN não estiver definido no servidor, o endpoint fica aberto (sem autenticação exigida), comportamento igual ao /send.

Códigos de status

Código	Condição
200	Todas as checagens resultaram em `pass` ou `warn` — nenhum `fail`.
503	Ao menos uma checagem retornou `fail`. Útil para alertas de monitoração.
401	Token ausente ou inválido.
404	Domínio informado não está configurado no servidor (`GET /check/{dominio}`).

Resposta

A resposta é sempre application/json com a seguinte estrutura:

{
  "public_ip": "<string|null>",
  "ok": true,
  "domains": [
    {
      "domain": "exemplo.com.br",
      "dkim": { "status": "pass", "message": "Chave pública confere com a privada local." },
      "spf":  { "status": "pass", "message": "IP autorizado pelo SPF do domínio." },
      "dmarc": { "status": "pass", "message": "Registro _dmarc encontrado e bem-formado." }
    }
  ]
}

Campos

Campo	Tipo	Descrição
`public_ip`	string \| null	IP público detectado pelo servidor, usado na checagem SPF. `null` se não foi possível determinar.
`ok`	bool	`true` se nenhum domínio tem checagem com `status: fail`. Espelha o código HTTP (200 vs 503).
`domains`	array	Lista de resultados por domínio.
`domains[].domain`	string	Nome do domínio validado.
`domains[].dkim`	objeto	Resultado da checagem DKIM.
`domains[].spf`	objeto	Resultado da checagem SPF.
`domains[].dmarc`	objeto	Resultado da checagem DMARC.

Cada checagem (dkim, spf, dmarc) contém:

Campo	Tipo	Descrição
`status`	string	`pass`, `warn` ou `fail`.
`message`	string	Descrição legível do resultado.

Significado de cada `status`

Valor	Significado
`pass`	Configuração correta, envio autorizado.
`warn`	Situação ambígua; envio pode funcionar, mas há risco. Exemplo: IP público indeterminável no SPF.
`fail`	Configuração incorreta ou ausente; provável rejeição ou spam.

O que cada checagem verifica

DKIM — consulta <selector>._domainkey.<dominio> e compara a chave pública publicada (SPKI) com a chave privada local. Detecta registro ausente, chave em formato PKCS#1 (precisa ser SPKI) e divergência entre as chaves.

SPF — verifica se public_ip está autorizado pelo registro SPF do domínio, resolvendo mecanismos ip4, ip6, a, mx, include e all (limite de 10 lookups DNS). Resulta em warn se o IP público não puder ser determinado.

DMARC — confirma que _dmarc.<dominio> existe e está bem-formado.

Exemplos

Validar todos os domínios

curl -s -w "\nHTTP %{http_code}\n" \
  -H "X-Auth-Token: {TOKEN}" \
  https://mxout.203.0.113.x/check

Resposta com todos os domínios em dia (HTTP 200):

{
  "public_ip": "203.0.113.42",
  "ok": true,
  "domains": [
    {
      "domain": "empresa.com.br",
      "dkim":  { "status": "pass", "message": "Chave pública confere com a privada local." },
      "spf":   { "status": "pass", "message": "IP 203.0.113.42 autorizado pelo SPF." },
      "dmarc": { "status": "pass", "message": "Registro _dmarc encontrado e bem-formado." }
    },
    {
      "domain": "filial.com.br",
      "dkim":  { "status": "pass", "message": "Chave pública confere com a privada local." },
      "spf":   { "status": "warn", "message": "IP público não pôde ser determinado; SPF não verificado." },
      "dmarc": { "status": "pass", "message": "Registro _dmarc encontrado e bem-formado." }
    }
  ]
}

Resposta quando um domínio falha (HTTP 503):

{
  "public_ip": "203.0.113.42",
  "ok": false,
  "domains": [
    {
      "domain": "empresa.com.br",
      "dkim":  { "status": "fail", "message": "Chave pública não encontrada em DNS." },
      "spf":   { "status": "pass", "message": "IP 203.0.113.42 autorizado pelo SPF." },
      "dmarc": { "status": "pass", "message": "Registro _dmarc encontrado e bem-formado." }
    }
  ]
}

Validar um domínio específico

curl -s -w "\nHTTP %{http_code}\n" \
  -H "X-Auth-Token: {TOKEN}" \
  https://mxout.203.0.113.x/check/empresa.com.br

Se o domínio não estiver configurado (HTTP 404):

{
  "error": "domínio não configurado"
}

Quando usar

Use /check para monitoração contínua: dashboards, probes de Uptime Robot, Prometheus Blackbox Exporter ou qualquer sistema que consulte periodicamente a postura de DNS.

O código HTTP 503 em caso de falha permite que monitores alertem sem precisar interpretar o corpo da resposta.

Para validação pontual antes de um envio ou em pipelines de CI, use o comando de linha de comando — ele não exige o servidor em execução:

CLI — mxout check

Outros recursos relacionados:

POST /send — envia mensagens autenticadas pelo mesmo token.
Configuração — define domínios, seletores e MXOUT_AUTH_TOKEN.

By Borlot.com.br on 02/06/2026

# GET /check

# Endpoints

# Autenticação

# Códigos de status

# Resposta

# Campos

# Significado de cada `status`

# O que cada checagem verifica

# Exemplos

# Validar todos os domínios

# Validar um domínio específico

# Quando usar

Tags