API SMTP IAGENTEsmtp — envio de email transacional via SMTP e REST

Conexão SMTP

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

Limites da Conexão SMTP

Portas SMTP, IMAP e POP3

O IAGENTEsmtp opera apenas no envio (protocolo SMTP). Para referência, abaixo a tabela de portas dos três protocolos de email — SMTP (envio), IMAP e POP3 (recebimento). Use as portas SMTP 587 (recomendada, com STARTTLS) ou 465 (TLS implícito) para autenticar na API SMTP IAGENTEsmtp:

A porta 25 é frequentemente bloqueada por provedores de internet em conexões residenciais e até por alguns provedores cloud (AWS, GCP). Em produção, prefira 587 com STARTTLS — é o padrão moderno definido pela RFC 6409 para envio autenticado.

Como testar a conexão SMTP

Antes de integrar a API SMTP em produção, é boa prática testar a conexão e a autenticação no servidor SMTP do IAGENTEsmtp. Abaixo, três formas comuns de testar um servidor SMTP a partir da linha de comando:

1. Teste de conectividade com telnet

Verifica se a porta SMTP está aberta e se o servidor responde com o banner correto:

telnet smart.iagentesmtp.com.br 587
# resposta esperada: 220 smart.iagentesmtp.com.br ESMTP

2. Teste de TLS com openssl

Verifica negociação TLS na porta 587 (STARTTLS) ou 465 (TLS implícito):

# porta 587 — STARTTLS
openssl s_client -starttls smtp -connect smart.iagentesmtp.com.br:587 -crlf

# porta 465 — TLS implícito (SMTPS)
openssl s_client -connect smart.iagentesmtp.com.br:465 -crlf

3. Teste de envio completo com swaks

O swaks (Swiss Army Knife for SMTP) é a ferramenta mais prática para testar envio real, autenticação e TLS de uma vez:

swaks --to destinatario@exemplo.com \
      --from remetente@seudominio.com.br \
      --server smart.iagentesmtp.com.br \
      --port 587 \
      --auth LOGIN \
      --auth-user SEU_API_USER \
      --auth-password SUA_API_KEY \
      --tls

Se o teste retornar 250 OK, a conexão e autenticação estão funcionando. Códigos de resposta começando com 5xx indicam erro permanente (autenticação inválida, remetente bloqueado), e 4xx indicam erro temporário (rate limit, conexão recusada). Em caso de erro persistente, verifique no painel se as credenciais estão corretas e se o domínio remetente tem SPF e DKIM configurados.

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

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

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

{
  "message": "success"
}

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

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

Parâmetros

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"

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

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

Parâmetros

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"

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

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

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

Inbound Mail (Recebimento de Email via API)

O recurso de inbound mail (também conhecido como inbound email, email inbound ou inbound gateway) permite que o IAGENTEsmtp encaminhe emails recebidos em um dominio configurado para uma URL de callback no seu servidor, via POST em formato JSON.

É a forma de receber e processar emails programaticamente — útil para parse de respostas, tickets de suporte por email, processamento de bounces externos, ou inbound mail tracking (rastreamento de emails recebidos com seus anexos, headers e remetente).

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

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

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