# Rate limit (controle)

O mxout é um relay de testes deliberadamente lento. Três mecanismos em conjunto impedem uso em produção:

• Cota por domínio: cada domínio remetente tem um teto por janela (padrão: 20 por hora e 100 por dia). Estourar a cota faz o POST /send retornar 429.
• Throttle de API: limite de requisições por minuto por IP em todos os endpoints (padrão: 20/min). Ao exceder, qualquer endpoint retorna 429 com o header Retry-After.
• Lentidão artificial: o /send processa um envio por vez e aplica um delay forçado por mensagem (padrão: 3 segundos). Isso é proposital — inviabiliza qualquer volume de disparo.

Os endpoints desta página, protegidos por X-Auth-Token, permitem ler e ajustar esses parâmetros.

# Autenticação

Todos os endpoints abaixo exigem o header:

X-Auth-Token: {TOKEN}

Token ausente ou incorreto retorna 401. Se MXOUT_AUTH_TOKEN não estiver definido no servidor, os endpoints ficam abertos.

# GET /ratelimit

Retorna os limites atuais, incluindo overrides por domínio.

# Exemplo de requisição

curl -s \
  -H "X-Auth-Token: {TOKEN}" \
  http://<IP do servidor>:8080/ratelimit

# Resposta — 200

{
  "api_rate_per_min": 20,
  "send_delay_secs": 3,
  "default_domain_limits": {
    "per_hour": 20,
    "per_day": 100
  },
  "per_domain": {
    "exemplo.com": {
      "per_hour": 5,
      "per_day": 20
    }
  }
}

# Campos da resposta

# PUT /ratelimit

Ajusta um ou mais limites. Campos ausentes no corpo não são alterados.

# Body (JSON parcial — todos os campos são opcionais)

{
  "api_rate_per_min": 20,
  "send_delay_secs": 3,
  "default_domain_limits": {
    "per_hour": 20,
    "per_day": 100
  },
  "domains": {
    "exemplo.com": {
      "per_hour": 5,
      "per_day": 20
    }
  }
}

O campo domains define overrides por domínio. Enviar domains substitui os overrides existentes dos domínios listados; domínios não listados permanecem sem alteração.

# Exemplo de requisição

curl -s -X PUT \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {TOKEN}" \
  http://<IP do servidor>:8080/ratelimit \
  -d '{
    "send_delay_secs": 5,
    "domains": {
      "cliente.com": { "per_hour": 10, "per_day": 50 }
    }
  }'

# Resposta — 200

{ "ok": true }

# Códigos de status

# Comportamento do 429

Há dois cenários distintos que geram 429:

# Throttle de API (por IP)

Qualquer endpoint retorna 429 quando o IP ultrapassa api_rate_per_min. A resposta inclui o header:

Retry-After: <segundos até a janela resetar>

Aguarde o intervalo indicado antes de enviar uma nova requisição.

# Cota de domínio (no /send)

O POST /send retorna 429 quando o domínio remetente esgota a cota horária ou diária. O corpo da resposta indica qual cota foi atingida e quando ela renova:

{
  "error": "cota do domínio excedida",
  "limit": "per_hour",
  "resets_at": "2026-06-07T15:00:00Z"
}

Aguarde até resets_at ou ajuste os limites via PUT /ratelimit.

# Observações sobre os defaults

Os valores padrão (20/hora, 100/dia, 20 req/min, 3 s de delay) são intencionalmente baixos. Aumentá-los não é errado para testes específicos, mas desvirtua o propósito do mxout como relay de desenvolvimento. Em especial, reduzir send_delay_secs a zero remove a serialização e permite disparos em volume — comportamento incompatível com o uso esperado.

Para uso em produção, utilize um relay dedicado com SPF, DKIM e DMARC configurados corretamente em infraestrutura própria.

Recursos relacionados:

• POST /send — endpoint de envio sujeito à cota por domínio.
• Configuração — variáveis de ambiente que definem os limites iniciais.