AllyOneMail / Enviar e-mails

Enviar E-mails

Um endpoint central para todo envio transacional ou de marketing.

POST /api/v1/send

{
  "from": "contato@empresa.com.br",
  "to": "cliente@destino.com",
  "subject": "Assunto do e-mail",
  "html": "<p>Conteúdo em HTML</p>",
  "text": "Conteúdo em texto puro (fallback)",
  "reply_to": "suporte@empresa.com.br",
  "attachments": [
    { "filename": "nota.pdf", "content": "<base64>", "type": "application/pdf" }
  ],
  "tags": ["boas-vindas"],
  "metadata": { "order_id": "1234" },
  "track_opens": true,
  "track_clicks": true,
  "test_mode": false
}

Campo	Obrigatório	Notas
`from`, `to`, `subject`	Sim	`subject` até 998 caracteres. `to` aceita string ou array.
`html` / `text`	Ao menos um	Envie os dois quando possível — `text` é o fallback de clientes sem HTML.
`attachments`	Não	Conteúdo em base64.
`track_opens` / `track_clicks`	Não	Ligados por padrão.
`test_mode`	Não	Valida o payload sem entregar de verdade — útil em CI.

Envio idempotente

Para evitar duplicidade em retry de rede, use POST /api/v2/messages — mesmo schema acima, mais idempotency_key (até 200 caracteres). A chave vale por 7 dias:

Situação	Resposta
Primeira chamada com a chave	Envio normal.
Mesma chave e mesmo conteúdo, envio já concluído	`200` com o `message_id` original e `"deduplicated": true` — nada é reenviado.
Mesma chave, primeira chamada ainda em andamento	`202` `{"status": "processing"}` — consulte de novo em instantes.
Mesma chave com conteúdo diferente	`409` `IDEMPOTENCY_CONFLICT`.