Guia de Desenvolvedores e API REST

A API RESTful do MailLeader permite a integração direta de recursos de envio de e-mails, consulta de telemetria, gerenciamento de listas e verificação de domínios diretamente nas suas aplicações (Node.js, Python, PHP, Ruby, Java, Go, C#, etc.).

Autenticação

Nas rotas privadas, autentique a conta usando uma chave de API em um destes formatos:

Também é aceito Authorization: ApiKey SUA_CHAVE_DE_API (Bearer é reservado para o token de sessão do painel). A chave completa só é exibida na criação; depois a listagem mostra apenas o prefixo. Guarde-a em local seguro: não é possível recuperá-la, apenas criar outra. As rotas públicas de formulários e pixels usam tokens próprios e estão descritas nos guias correspondentes.

Como Gerar uma Chave de API

Acesse o painel do MailLeader.

Navegue até Desenvolvedor > Chaves de API.

Clique em Criar Chave, informe uma descrição (ex: Backend Produção) e confirme.

Armazene a chave de forma segura no seu cofre de segredos ou variável de ambiente (.env). A chave nunca é exibida novamente após a criação.

Endereço Base (Base URL)

As rotas privadas documentadas aqui usam o prefixo /api/v1.

Endpoint de Envio de E-mails

Enviar um e-mail em JSON

POST /api/v1/mail/send

Use este endpoint para enviar uma mensagem transacional a um destinatário ou encaminhar um envio a uma lista autorizada. O exemplo abaixo usa JSON, sem anexos.

Parâmetros do Envio

Campo	Tipo	Obrigatório	Descrição
`from`	string	Sim	Endereço de e-mail do remetente (ex: `suporte@empresa.com.br`). Deve pertencer a um domínio ativo.
`fromName`	string	Sim	Nome de exibição do remetente (ex: `Equipe MailLeader`).
`to`	string	Opcional*	E-mail do destinatário. (Obrigatório se `listId` não for informado).
`listId`	string	Opcional*	ID de uma lista para disparo em massa. (Se omitido, `to` é obrigatório).
`subject`	string	Sim	Linha de assunto do e-mail.
`html`	string	Opcional	Conteúdo do e-mail formatado em HTML.
`text`	string	Opcional	Versão em texto puro da mensagem (altamente recomendada para entregabilidade).
`cc`	string	Opcional	Endereços em cópia separados por vírgula.

Informe text, html ou ambos. Para anexos, envie a mesma rota como multipart/form-data, com os campos de texto e o campo attachments repetido para cada arquivo (até 10 arquivos de 10 MiB cada). Também é possível enviar anexos por SMTP.

Exemplo com cURL

Cabeçalhos:

Exemplo com cURL:

Resposta de Sucesso (`201 Created`)

{
  "message": "E-mail enviado com sucesso",
  "messageId": "41e1e808-0c9d-7591-8a3b-30b4662d63c7@empresa.com.br",
  "accepted": ["cliente@exemplo.com"],
  "rejected": []
}

accepted e rejected listam os endereços aceitos e recusados na submissão SMTP. Aceito não significa entregue: acompanhe o estado em GET /api/v1/mail/logs ou pelo webhook smtp.email.delivered.

Endpoints de Logs e Telemetria

1. Consultar Histórico de Envios

GET /api/v1/mail/logs

Retorna a lista paginada e filtrável de mensagens e o status consolidado de entrega de cada destinatário.

Parâmetros de Query (`query string`)

Parâmetro	Tipo	Exemplo	Descrição
`page`	number	`1`	Página atual da consulta (início em 1).
`limit`	number	`20`	Quantidade de itens por página (máximo recomendado: 100).
`recipient`	string	`cliente@exemplo.com`	Filtro parcial ou exato por destinatário.
`domainId`	string (UUID)	`uuid...`	Filtro por domínio de envio.
`status`	string	`delivered`	Filtra por status: `sent`, `delivered`, `opened`, `bounced`, `deferred`.
`startDate`	string (ISO)	`2026-10-01T00:00:00Z`	Data inicial do intervalo (UTC).
`endDate`	string (ISO)	`2026-10-13T23:59:59Z`	Data final do intervalo (UTC).

Exemplo de Requisição

Exemplo de Resposta

{
  "data": [
    {
      "id": "e9b25f48-a0ef-4fce-bc28-1b5e0f7f3290",
      "recipient": "cliente@exemplo.com",
      "from": "contato@empresa.com.br",
      "subject": "Código de Verificação: 489201",
      "status": "delivered",
      "acceptedAt": "2026-10-13T21:10:00.000Z",
      "deliveredAt": "2026-10-13T21:10:02.000Z",
      "openedAt": "2026-10-13T21:15:30.000Z",
      "reason": null
    }
  ],
  "total": 1,
  "page": 1,
  "maxPage": 1
}

2. Exportar Logs de Envios

POST /api/v1/mail/logs/export

Gera um arquivo de exportação (CSV/JSON) consolidado com os critérios selecionados na consulta de logs.

Tratamento de Códigos de Resposta HTTP

O MailLeader segue os padrões da especificação HTTP:

Código	Significado	Descrição e Ação Recomendada
`200 OK` / `201 Created`	Sucesso	A requisição foi processada e a mensagem foi aceita para envio.
`400 Bad Request`	Erro de Validação	Dados obrigatórios ausentes, formato de e-mail inválido ou anexos acima de 10 arquivos ou 10 MiB por arquivo.
`401 Unauthorized`	Não Autorizado	Chave de API ausente ou inválida. Verifique o cabeçalho `x-api-key`.
`403 Forbidden`	Acesso Negado	Domínio não verificado, conta suspensa ou limite de capacidade do plano excedido.
`429 Too Many Requests`	Taxa Excedida	Muitas tentativas nas rotas de login, cadastro e recuperação de senha. Aguarde antes de tentar de novo.
`500 Internal Error`	Erro Interno	Falha temporária no processamento. Tente novamente em alguns segundos.

Estrutura de Resposta de Erro

{
  "statusCode": 400,
  "message": "validation.mail.from.empty",
  "error": "Bad Request"
}

Próximos Guias

Configure webhooks para receber notificações em tempo real em Webhooks.

Gerencie suas bases de dados em Listas de Contatos.

Crie formulários de captura em Formulários e leads.

Meça visitas e eventos consentidos em Pixels e eventos de sites.

Reutilize conteúdo em Templates de e-mail.

Veja exemplos prontos em Node.js, Python e PHP em Exemplos de Uso.

Guia de Desenvolvedores e API REST

Autenticação#

Como Gerar uma Chave de API#

Endereço Base (Base URL)#

Endpoint de Envio de E-mails#

Enviar um e-mail em JSON#

Parâmetros do Envio#

Exemplo com cURL#

Resposta de Sucesso (201 Created)#

Endpoints de Logs e Telemetria#

1. Consultar Histórico de Envios#

Parâmetros de Query (query string)#

Exemplo de Requisição#

Exemplo de Resposta#

2. Exportar Logs de Envios#

Tratamento de Códigos de Resposta HTTP#

Estrutura de Resposta de Erro#

Próximos Guias#