API — visão geral
O mxout expõe uma API HTTP para envio de e-mails, gestão de clientes e domínios, e verificação de saúde do serviço. Há também uma porta SMTP para aplicações que não falam HTTP.
Base
A API escuta no endereço configurado em listen do mxout.json. A porta padrão é 8080.
http://<IP do servidor>:8080O mxout foi projetado para rodar atrás de um proxy reverso (Traefik, Nginx) em rede privada.
Endpoints
Envio — credencial de cliente
| Método | Caminho | Descrição |
|---|---|---|
| POST | `/send-raw` | Envia um MIME já montado (preserva anexos e headers) |
| POST | `/send` | Envia a partir de campos (assunto, html, texto) |
Gestão — token de admin
| Método | Caminho | Descrição |
|---|---|---|
| GET POST | `/clients` | Clientes que podem enviar |
| GET PATCH DELETE | `/clients/{id}` | Detalhe, habilitar/desabilitar, remover |
| POST | `/clients/{id}/rotate` | Nova senha |
| PUT | `/clients/{id}/domains` | Domínios autorizados |
| GET POST | `/domains` | Domínios remetentes |
| GET | `/check` | Validação de DNS |
| GET | `/queue` | Estado das entregas |
| POST | `/queue/tick` | Drena a fila |
| GET PUT | `/ratelimit` | Cotas e freios |
| GET PUT | `/allowlist` | IPs autorizados |
Sem autenticação
| Método | Caminho | Descrição |
|---|---|---|
| GET | `/health` | Status de saúde |
Autenticação: duas credenciais, poderes disjuntos
| Credencial | Como se envia | Administra | Envia |
|---|---|---|---|
| Token de admin | X-Auth-Token: {TOKEN} |
sim | não |
| Cliente | Authorization: Basic base64(cli_id:senha) |
não | sim, nos domínios autorizados |
Até a v0.7.0 havia um token só, que fazia as duas coisas — e por isso não podia ser entregue a nenhuma aplicação: quem o recebesse poderia enviar por qualquer domínio, e um vazamento obrigaria a trocar o segredo de todas de uma vez. Separar os poderes é o que permite distribuir credencial por aplicação, revogando uma sem tocar nas outras.
O token de admin vem de MXOUT_AUTH_TOKEN. A comparação é feita em tempo constante.
Sem token configurado: se MXOUT_AUTH_TOKEN estiver ausente ou vazia, os endpoints de
gestão ficam abertos e o serviço registra um aviso na inicialização. Defina a variável em
qualquer ambiente.
As credenciais de cliente são criadas pela API — ver Clientes.
Formato de erros
Erros de validação retornam JSON com message_id igual a "-":
{
"message_id": "-",
"error": "descrição do erro"
}| Código HTTP | Situação |
|---|---|
| 400 | Campo from inválido, sem domínio, ou domínio sem kit DKIM configurado |
| 401 | Credencial ausente ou inválida (token de admin ou cliente) |
| 403 | Cliente não autorizado para o domínio, ou domínio ainda pending |
| 413 | Corpo da requisição acima de 8 MiB |
| 429 | Cota do domínio ou throttle de API |
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.