API de e-mail rápida, robusta e fácil de integrar.

Uma requisição JSON envia seus e-mails transacionais. Relatórios e webhooks mostram o que aconteceu com cada um.

  • RápidaResposta imediata e até 50 chamadas/s.
  • RobustaDatacenter Tier III e IPs monitorados.
  • Fácil de integrarExemplos de código em 8 linguagens.

Seu primeiro envio

Se a sua aplicação faz uma requisição HTTP, ela já envia pela MailGrid.

  1. Pegue as credenciais SMTP

    Host, usuário e senha ficam no painel da sua conta.

  2. Monte o JSON

    Remetente, emailDestino, assunto e mensagem são o mínimo.

  3. Faça o POST

    A resposta traz o id da mensagem para você rastrear a entrega.

  4. Acompanhe a entrega

    Receba o status por webhook ou consulte o endpoint /report/.

curl -X POST https://api.mailgrid.net.br/sendmail/ \
  -H "Content-Type: application/json" \
  -d '{
    "host_smtp": "HOST-SMTP",
    "usuario_smtp": "USUARIO-SMTP",
    "senha_smtp": "SENHA-SMTP",
    "emailRemetente": "nfe@suaempresa.com.br",
    "nomeRemetente": "Sua Empresa",
    "emailDestino": ["cliente@dominio.com.br"],
    "assunto": "Sua NF-e 004.812",
    "mensagem": "<p>Segue sua nota fiscal.</p>",
    "mensagemTipo": "html"
  }'
200 Resposta
[
  {
    "status": "MSG ENVIADA",
    "codigo": "200",
    "id": "1rDPyZ-0006kJ-2N",
    "to": "cliente@dominio.com.br"
  }
]

Parâmetros da requisição

Todos os campos vão no corpo JSON do POST /sendmail/.

Autenticação

host_smtpstringobrigatório

Host SMTP da sua conta.

usuario_smtpstringobrigatório

Usuário SMTP, o mesmo da autenticação por SMTP.

senha_smtpstringobrigatório

Senha do usuário SMTP.

Remetente e destinatários

emailRemetentestringobrigatório

Endereço do remetente, de um domínio autenticado.

nomeRemetentestring

Nome exibido para o destinatário.

emailReplystring

Endereço para onde vão as respostas.

emailDestinoarrayobrigatório

Destinatários, até 100 por chamada.

nomeDestinostring

Nome do destinatário.

emailDestinoCopiaarray

Cópia (CC), até 100 endereços.

emailDestinoCopiaOcultaarray

Cópia oculta (CCO), até 100 endereços.

Conteúdo

assuntostringobrigatório

Assunto da mensagem. Aceita variáveis {{nome}}.

mensagemstringobrigatório

Corpo da mensagem em HTML ou texto.

mensagemAltstring

Versão alternativa em texto simples.

mensagemTipohtml | text

Formato do corpo. Padrão: html.

mensagemEncodingbase64 | quoted-printable

Codificação do corpo. Padrão: base64.

Anexos e recursos extras

mensagemAnexosarray

Objetos com name, type (MIME) e content em Base64.

variaveisarray

Um objeto por destinatário, na mesma ordem de emailDestino.

listUnsubscribestring (URL HTTPS)

Endereço de descadastro em um clique. Aceita {{token}}.

listIdstring

Identificador estável da lista, enviado no cabeçalho List-ID.

Códigos de resposta

Cada destinatário recebe um objeto na resposta. O campo codigo diz o que aconteceu, e status traz o resumo em texto.

Exemplo de erro
[
  {
    "status": "ERRO DE ENVIO",
    "codigo": "204",
    "criptokey": "f87e7bf77c609d9537e146fb32d88418",
    "to": "seunome@seuemail.com"
  }
]

Sucesso

  • 200MSG ENVIADA. Mensagem aceita para entrega.

Conexão e autenticação

  • 207Falha de autenticação. Credenciais SMTP inválidas.
  • 204Erro de envio. Falha na conexão SMTP.

Requisição inválida

  • 208Faltam parâmetros. Algum campo obrigatório não foi enviado.
  • 211Encoding inválido. Use base64 ou quoted-printable.
  • 212Tipo inválido. Use html ou text.
  • 227Formato incorreto. emailDestino precisa ser um array.
  • 228Formato incorreto. emailDestinoCopia precisa ser um array.
  • 229Formato incorreto. emailDestinoCopiaOculta precisa ser um array.

Limites

  • 215Tamanho excedido. Mensagem ou anexo acima do limite.
  • 221Limite de contatos. Mais de 100 endereços em emailDestino.
  • 222Limite de contatos. Excedido em emailDestinoCopia.
  • 223Limite de contatos. Excedido em emailDestinoCopiaOculta.

Uma chamada, várias mensagens personalizadas

Variáveis por destinatário

Escreva {{nome}} no assunto ou na mensagem. Cada objeto de variaveis vale para o destinatário na mesma posição.

{
  "emailDestino": ["ana@exemplo.com.br", "bruno@exemplo.com.br"],
  "variaveis": [
    { "nome": "Ana", "pedido": "A1" },
    { "nome": "Bruno", "pedido": "B2" }
  ],
  "assunto": "Pedido {{pedido}} confirmado",
  "mensagem": "<p>Olá {{nome}}, pedido {{pedido}} aprovado.</p>"
}

Anexos em Base64

Notas fiscais, boletos e PDFs junto da mensagem, dentro do limite de 50 MB.

"mensagemAnexos": [{
  "name": "boleto_outubro.pdf",
  "type": "application/pdf",
  "content": "JVBERi0xLjQKJ..."
}]

Descadastro em um clique

Envie listUnsubscribe e a API adiciona os cabeçalhos que os grandes provedores exigem de remetentes de volume.

  • List-Unsubscribe: <https://seusite.com.br/sair/{{token}}>
  • List-Unsubscribe-Post: List-Unsubscribe=One-Click

Webhooks de entrega

Cadastre uma URL no painel e receba um POST em JSON quando cada mensagem chegar a um status final.

statusevento
1Sucesso. Mensagem entregue.
2Softbounce. Falha temporária na entrega.
0Hardbounce. Falha permanente na entrega.
  • Cada webhook tem um token, enviado em Authorization: Bearer. Valide e responda 401 se não conferir.
  • Qualquer resposta 2xx confirma o recebimento. Fora disso, o evento é reenviado.
  • Use o msgid para descartar eventos repetidos.
Documentação dos webhooks (abre em nova aba)
POST para a sua URL
{
  "msgid": "1q2w3e4r5t-ABC",
  "status": 1,
  "email_de": "no-reply@seu-dominio.com",
  "email_para": "cliente@destino.com",
  "mensagem": "Entregue com sucesso",
  "data_envio": "2025-08-25 14:05:36",
  "data_entrega": "2025-08-25 14:05:41",
  "sender": "mailer@seu-dominio.com",
  "sender_ip": "203.0.113.10",
  "sender_host": "mx1.seu-dominio.com",
  "delivery_ip": "198.51.100.22",
  "delivery_host": "mx.destino.com.br",
  "size": "12345"
}

Toda a referência em um só lugar

Endpoints, parâmetros, respostas e exemplos completos na documentação oficial da API.

Acessar a documentação (abre em nova aba)

Outros endpoints

Consulte relatórios e administre domínios e usuários SMTP pela mesma API.

Relatórios

  • POST/report/Envios de um período, com filtros por status, destinatário, remetente ou id.
  • POST/consolidate/Dados consolidados de um período, com filtro de sucesso ou erro.

Domínios

  • POST/domain/add/Adiciona um domínio de envio.
  • POST/domain/check/Verifica a configuração de um domínio.
  • POST/domain/list/Lista os domínios da conta.
  • POST/domain/remove/Remove um domínio.

Usuários SMTP

  • POST/authsmtp/add/Cria um usuário SMTP e devolve a senha gerada.
  • POST/authsmtp/psswd/Troca a senha de um usuário SMTP.
  • POST/authsmtp/remove/Remove um usuário SMTP.

Todos usam a base https://api.mailgrid.net.br e se autenticam com o token_auth da conta. Parâmetros completos na documentação.

Integração na sua linguagem

Exemplos prontos em PHP, Python, Node.js, C#, Java, Ruby, JavaScript e cURL. Se a sua não estiver lá, o suporte ajuda.