Enviar e-mail

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

posthttps://app.madmail.com.br/api/v1/emails

Requer autenticação: Authorization: Bearer us_SUA_CHAVE

Cabeçalhos

Idempotency-KeystringOpcional

Envie o cabeçalho opcional Idempotency-Key para tornar a requisição segura para novas tentativas. A chave pode ter até 256 caracteres. O servidor armazena o corpo canônico da requisição e se comporta da seguinte forma:

Mesma chave + mesmo corpo de requisição → retorna o emailId original com 200 OK, sem reenviar.
Mesma chave + corpo de requisição diferente → retorna 409 Conflict com code: NOT_UNIQUE para que você possa detectar a divergência.
Mesma chave enquanto outra requisição ainda está sendo processada → retorna 409 Conflict; tente novamente após um curto intervalo ou quando a primeira requisição terminar.

Os registros expiram após 24 horas. Use uma chave única por envio lógico (por exemplo, um ID de pedido ou de cadastro).

Tamanho:: 1–256

Corpo da requisição

tostring | array<string>Obrigatório

fromstringObrigatório

subjectstringOpcional

Opcional quando templateId é informado

Tamanho:: mín. 1

templateIdstringOpcional

ID de um template do painel

variablesobjectOpcional

replyTostring | array<string>Opcional

ccstring | array<string>Opcional

bccstring | array<string>Opcional

textstring | nullOpcional

Tamanho:: mín. 1

htmlstring | nullOpcional

Tamanho:: mín. 1

headersobjectOpcional

Cabeçalhos personalizados a serem incluídos nos e-mails

attachmentsarray<object>Opcional

Máx. de itens:: 10

filenamestringObrigatório

Tamanho:: mín. 1

contentstringObrigatório

Tamanho:: mín. 1

scheduledAtstringOpcional

Formato:: date-time

inReplyToIdstring | nullOpcional

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"
  }'

Resposta

200

Recupera o usuário

emailIdstringOpcional

{
  "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.

errorobjectObrigatório

codestringObrigatório

messagestringObrigatório

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