# IP allowlist

A IP allowlist controla quais servidores podem chamar a API do mxout. Antes de qualquer verificação de token, o mxout avalia o IP do cliente e rejeita com 403 os que não constam na lista.

O IP do cliente é lido do header X-Forwarded-For (o mxout fica atrás do Traefik). Na ausência do header, usa o IP da conexão TCP.

# Lista vazia = aberta

Quando a lista não tem nenhuma entrada, qualquer IP é aceito. Esse é o estado inicial — útil para validar a instalação antes de restringir o acesso.

Após confirmar que a integração funciona, adicione os IPs ou faixas dos seus servidores e a lista fecha automaticamente para externos.

# Formato das entradas

Cada entrada é um IP solto ou um bloco CIDR, em IPv4 ou IPv6:

Os exemplos nesta página usam faixas da RFC 5737 (203.0.113.x, 198.51.100.x), reservadas para documentação e sem roteamento real.

# Autenticação

Esses endpoints usam o mesmo header dos demais: X-Auth-Token comparado com MXOUT_AUTH_TOKEN. A checagem de allowlist ocorre antes da checagem de token, portanto um IP bloqueado recebe 403 e nunca chega à validação do token.

# GET /allowlist

Retorna a lista atual de IPs e faixas CIDR permitidos.

# Resposta

# Exemplo

curl -s \
  -H "X-Auth-Token: {TOKEN}" \
  https://mxout.203.0.113.x/allowlist

Resposta com entradas configuradas (HTTP 200):

{
  "allowlist": ["203.0.113.0/24", "198.51.100.7"]
}

Resposta quando a lista está vazia, ou seja, aberta (HTTP 200):

{
  "allowlist": []
}

# PUT /allowlist

Substitui a lista inteira pelas entradas enviadas no corpo. Para reabrir o acesso a todos os IPs, envie uma lista vazia.

# Corpo da requisição

{
  "allowlist": ["203.0.113.0/24", "198.51.100.7"]
}

O campo allowlist é obrigatório e deve ser um array de strings. Cada string é validada como IP ou CIDR antes de persistir.

# Resposta

# Exemplo — definir faixas permitidas

curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {TOKEN}" \
  -d '{"allowlist": ["203.0.113.0/24", "198.51.100.7"]}' \
  https://mxout.203.0.113.x/allowlist

Resposta (HTTP 200):

{
  "ok": true
}

# Exemplo — reabrir para todos (lista vazia)

curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {TOKEN}" \
  -d '{"allowlist": []}' \
  https://mxout.203.0.113.x/allowlist

# Exemplo — entrada inválida

curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {TOKEN}" \
  -d '{"allowlist": ["não-é-um-ip"]}' \
  https://mxout.203.0.113.x/allowlist

Resposta (HTTP 400):

{
  "error": "bad_cidr",
  "entry": "não-é-um-ip"
}

# Aviso: não se tranque para fora

Ao preencher a lista pela primeira vez, inclua o IP do servidor ou da aplicação que chama o mxout. Se esquecer, esse servidor passa a receber 403 em todas as chamadas.

A recuperação é simples: como a lista vazia reabre o acesso, basta enviar um PUT /allowlist com "allowlist": [] a partir de qualquer IP. Depois corrija a lista com as entradas corretas.

# Recursos relacionados

• GET /check — valida DNS dos domínios remetentes.
• POST /send — envia mensagens via SMTP com assinatura DKIM.
• Autenticação — detalhes sobre X-Auth-Token e MXOUT_AUTH_TOKEN.