# API — visão geral

O mxout expõe uma API HTTP para envio de e-mails e verificação de saúde do serviço.

# Base

A API escuta no endereço configurado em listen do mxout.json. A porta padrão é 8080.

http://<IP do servidor>:8080

O mxout foi projetado para rodar atrás de um proxy reverso (Traefik, Nginx) em rede privada.

# Endpoints

Veja a referência completa de cada endpoint:

• POST /send
• GET /health

# Autenticação

O mxout usa autenticação por token estático via header X-Auth-Token.

O token é definido pela variável de ambiente MXOUT_AUTH_TOKEN. A comparação é feita em tempo constante para evitar ataques de timing.

Sem token configurado: se MXOUT_AUTH_TOKEN estiver ausente ou vazia, o endpoint /send fica aberto e o serviço registra um aviso na inicialização. Use somente atrás de rede privada com acesso restrito.

Exemplo de header:

X-Auth-Token: {TOKEN}

# Formato de erros

Erros de validação retornam JSON com message_id igual a "-":

{
  "message_id": "-",
  "error": "descrição do erro"
}

# Correlação com o ledger

O campo message_id retornado pelo /send aparece nos eventos de log estruturado (stdout) e no header Message-ID do e-mail entregue. Use-o para rastrear o ciclo de vida de uma mensagem no Ledger.