Documentação API

IAGENTEsmtp API

Email transacional de alta entregabilidade via SMTP e REST API com webhooks, tracking e configuração SPF/CNAME.

Conexão SMTP

Para enviar emails via protocolo SMTP, utilize as configuracoes abaixo no seu cliente de email ou aplicacao.

Parâmetro Valor
Host smart.iagentesmtp.com.br
Portas 25 ou 587
Autenticação Login e senha fornecidos no painel
Criptografia TLS (recomendado na porta 587)

Limites da Conexão SMTP

Limite Valor
Tamanho maximo da mensagem 30 MB
Maximo de destinatarios por mensagem 500
Maximo de conexoes simultaneas 50

API REST

A API REST permite enviar emails e consultar atividades/tráfego via requisições HTTP. Todas as requisições devem ser enviadas via POST.

Base URL

https://api.iagentesmtp.com.br/api/v3/

Autenticação

Todas as requisições devem incluir os parâmetros api_user e api_key no corpo da requisição (POST). As credenciais sao as mesmas utilizadas para a conexão SMTP.

Parâmetros do Envio

POST /send/ Envio de emails

Endpoint para envio de emails individuais, múltiplos, com anexos e personalizados.

Parâmetro Tipo Obrigatório Descrição
api_user string Sim Usuario da API (mesmo do SMTP)
api_key string Sim Chave da API (mesmo do SMTP)
from string Sim Email do remetente
fromname string Nao Nome do remetente
to string Sim Email do destinatario (individual) ou lista separada por ;
subject string Sim Assunto do email
html string Sim* Corpo do email em HTML
text string Sim* Corpo do email em texto plano (*obrigatório se html nao for enviado)
cc string Nao Email(s) em copia, separados por ;
bcc string Nao Email(s) em copia oculta, separados por ;
replyto string Nao Email de resposta
headers string (JSON) Nao Headers customizados em formato JSON
files file Nao Arquivo(s) em anexo (multipart/form-data)
content string (JSON) Nao Anexos em base64: {"nome_arquivo.pdf": "base64_content"}
sub string (JSON) Nao Substituicoes para personalizacao. Ex: {"%nome%": ["Joao", "Maria"]}

Envio Individual

curl -X POST https://api.iagentesmtp.com.br/api/v3/send/ \
  -d "api_user=SEU_USUARIO" \
  -d "api_key=SUA_CHAVE" \
  -d "from=contato@seudominio.com.br" \
  -d "fromname=Minha Empresa" \
  -d "to=destinatario@email.com" \
  -d "subject=Assunto do Email" \
  -d "html=<h1>Ola!</h1><p>Este e um email de teste.</p>"
{
  "api_user": "SEU_USUARIO",
  "api_key": "SUA_CHAVE",
  "from": "contato@seudominio.com.br",
  "fromname": "Minha Empresa",
  "to": "destinatario@email.com",
  "subject": "Assunto do Email",
  "html": "<h1>Ola!</h1><p>Este e um email de teste.</p>"
}
Resposta de Sucesso
{
  "message": "success"
}
Resposta de Erro
{
  "message": "error",
  "errors": [
    "Descrição do erro"
  ]
}

Envio para Múltiplos Destinatarios

curl -X POST https://api.iagentesmtp.com.br/api/v3/send/ \
  -d "api_user=SEU_USUARIO" \
  -d "api_key=SUA_CHAVE" \
  -d "from=contato@seudominio.com.br" \
  -d "fromname=Minha Empresa" \
  -d "to=email1@dominio.com;email2@dominio.com;email3@dominio.com" \
  -d "subject=Comunicado Geral" \
  -d "html=<p>Mensagem para múltiplos destinatarios.</p>"
{
  "api_user": "SEU_USUARIO",
  "api_key": "SUA_CHAVE",
  "from": "contato@seudominio.com.br",
  "fromname": "Minha Empresa",
  "to": "email1@dominio.com;email2@dominio.com;email3@dominio.com",
  "subject": "Comunicado Geral",
  "html": "<p>Mensagem para múltiplos destinatarios.</p>"
}

Envio com Anexos

Para enviar arquivos em anexo, utilize multipart/form-data com o parâmetro files, ou envie via base64 com o parâmetro content.

Anexo via multipart/form-data

curl -X POST https://api.iagentesmtp.com.br/api/v3/send/ \
  -F "api_user=SEU_USUARIO" \
  -F "api_key=SUA_CHAVE" \
  -F "from=contato@seudominio.com.br" \
  -F "fromname=Minha Empresa" \
  -F "to=destinatario@email.com" \
  -F "subject=Email com Anexo" \
  -F "html=<p>Segue documento em anexo.</p>" \
  -F "files=@/caminho/para/arquivo.pdf"

Anexo via Base64

curl -X POST https://api.iagentesmtp.com.br/api/v3/send/ \
  -d "api_user=SEU_USUARIO" \
  -d "api_key=SUA_CHAVE" \
  -d "from=contato@seudominio.com.br" \
  -d "to=destinatario@email.com" \
  -d "subject=Email com PDF" \
  -d "html=<p>Segue o PDF.</p>" \
  -d 'content={"relatorio.pdf": "JVBERi0xLjQKJ..."}'
{
  "api_user": "SEU_USUARIO",
  "api_key": "SUA_CHAVE",
  "from": "contato@seudominio.com.br",
  "to": "destinatario@email.com",
  "subject": "Email com PDF",
  "html": "<p>Segue o PDF.</p>",
  "content": {
    "relatorio.pdf": "JVBERi0xLjQKJ..."
  }
}

Envio Personalizado (Substituicoes)

Use o parâmetro sub para enviar emails personalizados para cada destinatario listado no campo to. A quantidade de valores em cada array de substituicao deve corresponder a quantidade de destinatarios.

curl -X POST https://api.iagentesmtp.com.br/api/v3/send/ \
  -d "api_user=SEU_USUARIO" \
  -d "api_key=SUA_CHAVE" \
  -d "from=contato@seudominio.com.br" \
  -d "fromname=Minha Empresa" \
  -d "to=joao@email.com;maria@email.com" \
  -d "subject=Ola %nome%, temos novidades!" \
  -d "html=<p>Ola %nome%, seu código e %código%.</p>" \
  -d 'sub={"%nome%": ["Joao", "Maria"], "%código%": ["ABC123", "XYZ789"]}'
{
  "api_user": "SEU_USUARIO",
  "api_key": "SUA_CHAVE",
  "from": "contato@seudominio.com.br",
  "fromname": "Minha Empresa",
  "to": "joao@email.com;maria@email.com",
  "subject": "Ola %nome%, temos novidades!",
  "html": "<p>Ola %nome%, seu código e %código%.</p>",
  "sub": {
    "%nome%": ["Joao", "Maria"],
    "%código%": ["ABC123", "XYZ789"]
  }
}

Histórico de Atividades

POST /activity/ Consultar histórico de emails

Consulta o histórico de atividades dos emails enviados (entregas, aberturas, cliques, bounces, etc.).

Parâmetros

Parâmetro Tipo Obrigatório Descrição
api_user string Sim Usuario da API
api_key string Sim Chave da API
data_ini string Sim Data inicial no formato YYYY-MM-DD
data_fim string Sim Data final no formato YYYY-MM-DD
event string Nao Filtrar por tipo de evento: enviado, entregue, falha, bounce, leitura, clique, cancelamento
email string Nao Filtrar por email de destinatario

Exemplo

curl -X POST https://api.iagentesmtp.com.br/api/v3/activity/ \
  -d "api_user=SEU_USUARIO" \
  -d "api_key=SUA_CHAVE" \
  -d "data_ini=2026-01-01" \
  -d "data_fim=2026-01-31" \
  -d "event=entregue"
Resposta 200 OK
{
  "message": "success",
  "data": [
    {
      "email": "destinatario@email.com",
      "event": "entregue",
      "timestamp": "2026-01-15 14:32:10",
      "subject": "Assunto do email",
      "from": "contato@seudominio.com.br",
      "ip": "189.1.2.3",
      "user_agent": "Mozilla/5.0",
      "url": ""
    }
  ]
}

Tráfego

POST /traffic/ Estatisticas de tráfego

Retorna estatisticas agregadas de tráfego de envio por periodo.

Parâmetros

Parâmetro Tipo Obrigatório Descrição
api_user string Sim Usuario da API
api_key string Sim Chave da API
data_ini string Sim Data inicial no formato YYYY-MM-DD
data_fim string Sim Data final no formato YYYY-MM-DD

Exemplo

curl -X POST https://api.iagentesmtp.com.br/api/v3/traffic/ \
  -d "api_user=SEU_USUARIO" \
  -d "api_key=SUA_CHAVE" \
  -d "data_ini=2026-01-01" \
  -d "data_fim=2026-01-31"
Resposta 200 OK
{
  "message": "success",
  "data": [
    {
      "date": "2026-01-15",
      "requests": 1200,
      "delivered": 1180,
      "bounces": 12,
      "opens": 450,
      "clicks": 89,
      "spam_reports": 2,
      "unsubscribes": 5
    }
  ]
}

Configuração DNS

SPF

Para garantir a melhor entregabilidade dos seus emails, configure o registro SPF no DNS do seu dominio de envio. Adicione o seguinte registro TXT:

v=spf1 include:iagentesmtp.com.br ~all

Se voce ja possui um registro SPF existente, adicione o include:iagentesmtp.com.br antes do ~all ou -all:

v=spf1 include:_spf.google.com include:iagentesmtp.com.br ~all

CNAME Tracking

Para rastrear aberturas e cliques nos seus emails com seu proprio dominio, configure um registro CNAME no DNS:

Tipo Nome Valor
CNAME email (ou subdominio de sua escolha) track.iagentesmtp.com.br

Apos a configuração, informe o subdominio no painel do IAGENTEsmtp para ativar o tracking personalizado. Exemplo: se voce configurou email.seudominio.com.br, os links de rastreamento usarao esse subdominio.

Webhooks

Os webhooks permitem receber notificacoes em tempo real sobre os eventos dos seus emails. Configure a URL de callback no painel do IAGENTEsmtp.

Quando um evento ocorre, o sistema envia uma requisição POST para a URL configurada com os dados do evento em formato JSON.

Tipos de Eventos

Evento Descrição
enviado O email foi aceito pelo servidor de envio e esta na fila para entrega
entregue O email foi entregue com sucesso ao servidor de destino
falha Houve uma falha temporaria na entrega (soft bounce)
bounce O email foi rejeitado permanentemente pelo servidor de destino (hard bounce)
leitura O destinatario abriu o email
clique O destinatario clicou em um link do email
cancelamento O destinatario cancelou a inscricao (unsubscribe)

Formato do Webhook

POST https://seusite.com.br/webhook/smtp

Content-Type: application/json

{
  "event": "entregue",
  "email": "destinatario@email.com",
  "timestamp": "2026-01-15 14:32:10",
  "subject": "Assunto do email",
  "from": "contato@seudominio.com.br",
  "message_id": "<abc123@iagentesmtp.com.br>",
  "ip": "189.1.2.3",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "url": "",
  "reason": ""
}

Campos do Webhook

Campo Tipo Descrição
event string Tipo do evento
email string Email do destinatario
timestamp string Data/hora do evento
subject string Assunto do email
from string Remetente do email
message_id string ID único da mensagem
ip string IP do destinatario (em eventos de leitura/clique)
user_agent string User agent do destinatario (em eventos de leitura/clique)
url string URL clicada (apenas no evento clique)
reason string Motivo do erro (em eventos de falha e bounce)

Inbound Mail (Recebimento)

O IAGENTEsmtp pode encaminhar emails recebidos em um dominio configurado para uma URL de callback via POST, em formato JSON.

Para configurar, entre em contato com o suporte para apontar o MX do seu dominio para os servidores IAGENTEsmtp e cadastrar a URL de callback.

Formato do Inbound

POST https://seusite.com.br/webhook/inbound

Content-Type: application/json

{
  "from": "remetente@dominio.com",
  "from_name": "Nome do Remetente",
  "to": "destinatario@seudominio.com.br",
  "cc": "copia@outro.com",
  "subject": "Assunto do email recebido",
  "text": "Corpo do email em texto plano",
  "html": "<p>Corpo do email em HTML</p>",
  "headers": {
    "Message-Id": "<msg123@dominio.com>",
    "Date": "Thu, 15 Jan 2026 14:32:10 -0300",
    "Content-Type": "multipart/mixed"
  },
  "attachments": [
    {
      "filename": "documento.pdf",
      "content_type": "application/pdf",
      "size": 102400,
      "content": "JVBERi0xLjQKJ..."
    }
  ],
  "spam_score": 1.2,
  "timestamp": "2026-01-15 14:32:10"
}

Campos do Inbound

Campo Tipo Descrição
from string Email do remetente
from_name string Nome do remetente
to string Email do destinatario
cc string Emails em copia
subject string Assunto do email
text string Corpo em texto plano
html string Corpo em HTML
headers object Headers originais do email
attachments array Lista de anexos (filename, content_type, size, content em base64)
spam_score float Pontuacao de spam (quanto menor, melhor)
timestamp string Data/hora do recebimento

Precisa de ajuda? Entre em contato com nosso suporte tecnico pelo WhatsApp ou acesse a Central de Ajuda.