POST /send
O endpoint /send recebe um e-mail em JSON e entrega para cada destinatário via SMTP direto, com assinatura DKIM.
Headers
| Header | Valor esperado | Obrigatório |
|---|---|---|
Content-Type |
application/json |
Sim |
X-Auth-Token |
Valor de MXOUT_AUTH_TOKEN |
Sim (se auth configurada) |
Corpo da requisição
O corpo deve ser JSON com os seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
from |
string | Sim | Remetente. Formatos: "Nome <a@dominio>" ou "a@dominio". O domínio determina o kit DKIM usado. |
to |
array de strings | Sim | Lista de destinatários. Aceita um ou mais endereços. |
subject |
string | Sim | Assunto do e-mail. |
html |
string | Não | Corpo HTML do e-mail. |
text |
string | Não | Corpo em texto simples. |
Se html e text forem enviados juntos, o e-mail vira multipart/alternative. Se nenhum for enviado, o corpo é vazio.
O tamanho máximo do corpo da requisição é 5 MiB.
Exemplo de requisição
curl -X POST http://<IP do servidor>:8080/send \
-H "Content-Type: application/json" \
-H "X-Auth-Token: {TOKEN}" \
-d '{
"from": "Sistema <noreply@exemplo.com>",
"to": ["usuario@destino.com", "outro@destino.com"],
"subject": "Confirmação de cadastro",
"html": "<p>Olá! Seu cadastro foi confirmado.</p>",
"text": "Olá! Seu cadastro foi confirmado."
}'Resposta de sucesso
HTTP 200 com JSON contendo o message_id e o resultado por destinatário:
{
"message_id": "<20260601120000.abc123@exemplo.com>",
"results": [
{
"to": "usuario@destino.com",
"ok": true,
"detail": "entregue via mail.destino.com: 250 OK"
},
{
"to": "outro@destino.com",
"ok": true,
"detail": "entregue via mx1.destino.com: 250 Message accepted"
}
]
}Resposta com falha parcial
O mxout retorna HTTP 200 mesmo se um ou mais destinatários falharem. Verifique o campo ok de cada entrada em results:
{
"message_id": "<20260601120001.def456@exemplo.com>",
"results": [
{
"to": "usuario@destino.com",
"ok": true,
"detail": "entregue via mail.destino.com: 250 OK"
},
{
"to": "inexistente@dominio-invalido.com",
"ok": false,
"detail": "falha na resolução MX: no such host"
}
]
}Códigos de status HTTP
| Código | Situação |
|---|---|
| 200 | Requisição aceita e processada. Verifique ok por destinatário. |
| 400 | from inválido, sem domínio, ou domínio sem kit DKIM configurado. |
| 401 | X-Auth-Token ausente ou inválido. |
| 413 | Corpo da requisição acima de 5 MiB. |
Retry e comportamento por destinatário
Para cada destinatário, o mxout executa as seguintes etapas em sequência: monta o MIME, assina com DKIM, resolve o registro MX e tenta entrega SMTP.
Em caso de falha temporária (erro de conexão ou resposta 4xx do servidor remoto), o mxout faz retry com os intervalos: imediato, +5 s, +10 s, +30 s.
Respostas 5xx do servidor remoto são tratadas como falha permanente e abortam as tentativas.
O campo detail na resposta traz a mensagem do servidor SMTP no sucesso ("entregue via <host>: <resposta SMTP>") ou a descrição do erro na falha.
Veja como correlacionar entregas usando o Ledger e como configurar domínios DKIM em Configuração.