Enviar e-mail

Envie um e-mail transacional pela API pública.

POST /v1/emails

Exemplo de requisição

curl -X POST "https://app.madmail.com.br/api/v1/emails" \
  -H "Authorization: Bearer us_SUA_CHAVE" \
  -H "Idempotency-Key: valor" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "cliente@exemplo.com",
    "from": "cliente@exemplo.com"
  }'

Parâmetros

Nome	Local	Obrigatório	Tipo	Descrição
`Idempotency-Key`	header	Não	string

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`to`	string \| array<string>	Sim
`from`	string	Sim
`subject`	string	Não	Opcional quando templateId é informado
`templateId`	string	Não	ID de um template do painel
`variables`	object	Não
`replyTo`	string \| array<string>	Não
`cc`	string \| array<string>	Não
`bcc`	string \| array<string>	Não
`text`	string \| null	Não
`html`	string \| null	Não
`headers`	object	Não	Cabeçalhos personalizados a serem incluídos nos e-mails
`attachments`	array<object>	Não
`scheduledAt`	string	Não
`inReplyToId`	string \| null	Não

Exemplo

{
  "to": "cliente@exemplo.com",
  "from": "cliente@exemplo.com"
}

Respostas

200 — Recupera o usuário

Campo	Tipo	Descrição
`emailId`	string

Exemplo de resposta

{
  "emailId": "abc123"
}

400 — O template referenciado por `templateId` não tem corpo enviável e o e-mail não foi criado: em HTML personalizado, nenhum HTML salvo; no editor visual, nenhum bloco com conteúdo (o e-mail sairia em branco). A mensagem nomeia o template e o id. Recusa INTRODUZIDA NESTA VERSÃO — antes destes casos a API respondia 200 e o destinatário recebia um e-mail sem corpo. Uma exceção vale para as DUAS rotas: um envio cujos endereços de `to` estejam TODOS na lista de supressão nunca produz este 400. Em `POST /v1/emails` o envio para antes de o template ser resolvido; em `POST /v1/emails/batch` o item suprimido é apenas registrado no log e pulado, sem contar para a regra do 400 — e se o lote inteiro for assim, a resposta é 200. Nada é enviado nesses caminhos, então também não há e-mail em branco; o que se perde é o aviso de que o template está sem corpo.

Campo	Tipo	Descrição
`error`	object

Exemplo de resposta

{
  "error": {
    "code": "string",
    "message": "string"
  }
}