Documentação API SMTP

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

API de envio de email transacional de alta entregabilidade. SMTP autenticado nas portas 25/465/587, REST API, webhooks de entrega, inbound mail e configuração SPF/CNAME.

← Documentação das APIs · API WhatsApp e SDR · API Email Marketing · API SMS
Quickstart

Integre ainda hoje.

REST pra disparar por evento — ou sem escrever código, apontando seu sistema pro relay SMTP.

POST /api/v3/send
$ curl -X POST https://api.iagentesmtp.com.br/api/v3/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
    "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
    "subject": "Pedido confirmado",
    "html": "<p>Seu pedido saiu para entrega.</p>"
  }'
<?php
$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_user' => 'SEU_API_USER',
        'api_key' => 'SUA_API_KEY',
        'to' => [['email' => 'destinatario@email.com', 'name' => 'Fulano']],
        'from' => ['name' => 'Minha Empresa', 'email' => 'contato@seudominio.com.br'],
        'subject' => 'Pedido confirmado',
        'html' => '<p>Seu pedido saiu para entrega.</p>',
    ]),
]);
$resposta = curl_exec($ch);
// Node.js 18+ (fetch nativo)
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/send', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        api_user: 'SEU_API_USER',
        api_key: 'SUA_API_KEY',
        to: [{ email: 'destinatario@email.com', name: 'Fulano' }],
        from: { name: 'Minha Empresa', email: 'contato@seudominio.com.br' },
        subject: 'Pedido confirmado',
        html: '<p>Seu pedido saiu para entrega.</p>',
    }),
});
# pip install requests
import requests

resp = requests.post('https://api.iagentesmtp.com.br/api/v3/send', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'to': [{'email': 'destinatario@email.com', 'name': 'Fulano'}],
    'from': {'name': 'Minha Empresa', 'email': 'contato@seudominio.com.br'},
    'subject': 'Pedido confirmado',
    'html': '<p>Seu pedido saiu para entrega.</p>',
})
print(resp.text)
# Sem escrever código: aponte seu sistema pro relay
Host:     smart.iagentesmtp.com.br
Portas:   587 (STARTTLS, recomendada) · 465 (TLS) · 25
Usuário:  login da sua conta
Senha:    definida no painel

# Pronto — todo envio do seu sistema já sai pela IAGENTE,
# com logs em tempo real, webhooks e reputação monitorada.

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

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:

Protocolo Função Portas Suportado pelo IAGENTEsmtp
SMTP (Simple Mail Transfer Protocol) Envio de email 25 (legado), 465 (SMTPS/TLS), 587 (STARTTLS, recomendado) Sim — envio via SMTP autenticado
IMAP (Internet Message Access Protocol) Recebimento síncrono (mantém no servidor) 143 (não criptografado), 993 (IMAPS/TLS) Não — apenas envio. Para receber emails via API, veja Inbound Mail
POP3 (Post Office Protocol v3) Recebimento (download local + remoção do servidor) 110 (não criptografado), 995 (POP3S/TLS) Não — apenas envio

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 o histórico de eventos via requisições HTTP. Todas as requisições devem ser enviadas via POST, com corpo em JSON e header Content-Type: application/json.

Base URL

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

Autenticação

Todas as requisições devem incluir os campos api_user e api_key no corpo JSON. As credenciais sao as mesmas utilizadas para a conexão SMTP. Recomendamos armazenar as credenciais em variaveis de ambiente — nunca no código-fonte.

Parâmetros do Envio

POST /send Envio de emails

Endpoint para envio de emails simples, múltiplos, com anexos, com template 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)
to array Sim Destinatarios: [{"email": "...", "name": "..."}] — máximo de 500 por requisição
to[].custom object Nao Valores de personalização por destinatario (ver Envio Personalizado)
from object Sim Remetente: {"name": "...", "email": "...", "reply_to": "..."} (reply_to opcional)
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)
campanhaid string Nao Seu identificador interno, opcional
attachments array Nao Anexos: [{"filename": "...", "type": "...", "content": "base64"}]
templateid string Nao Token de um template previamente cadastrado no painel (usado no lugar de html/text)

Envio Simples

curl -X POST https://api.iagentesmtp.com.br/api/v3/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
    "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
    "subject": "Assunto do Email",
    "html": "<h1>Ola!</h1><p>Este e um email de teste.</p>"
  }'
<?php
$payload = [
    'api_user' => 'SEU_API_USER',
    'api_key'  => 'SUA_API_KEY',
    'to'       => [['email' => 'destinatario@email.com', 'name' => 'Fulano']],
    'from'     => ['name' => 'Minha Empresa', 'email' => 'contato@seudominio.com.br'],
    'subject'  => 'Assunto do Email',
    'html'     => '<h1>Ola!</h1><p>Este e um email de teste.</p>',
];

$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    to: [{ email: 'destinatario@email.com', name: 'Fulano' }],
    from: { name: 'Minha Empresa', email: 'contato@seudominio.com.br' },
    subject: 'Assunto do Email',
    html: '<h1>Ola!</h1><p>Este e um email de teste.</p>',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/send', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'to': [{'email': 'destinatario@email.com', 'name': 'Fulano'}],
    'from': {'name': 'Minha Empresa', 'email': 'contato@seudominio.com.br'},
    'subject': 'Assunto do Email',
    'html': '<h1>Ola!</h1><p>Este e um email de teste.</p>',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
  "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br", "reply_to": "respostas@seudominio.com.br"},
  "subject": "Assunto do Email",
  "html": "<h1>Ola!</h1><p>Este e um email de teste.</p>",
  "text": "Ola! Este e um email de teste.",
  "campanhaid": "seu identificador interno, opcional"
}
Resposta de Sucesso
{
  "status": "ok",
  "message": "1 recipient(s)",
  "size": "2KB"
}
Resposta de Erro
{
  "status": "failed",
  "message": "invalid json format"
}

Envio para Múltiplos Destinatarios

Informe até 500 destinatarios por requisição no array to.

curl -X POST https://api.iagentesmtp.com.br/api/v3/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "to": [
      {"email": "email1@dominio.com", "name": "Fulano1"},
      {"email": "email2@dominio.com", "name": "Fulano2"},
      {"email": "email3@dominio.com", "name": "Fulano3"}
    ],
    "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
    "subject": "Comunicado Geral",
    "html": "<p>Mensagem para múltiplos destinatarios.</p>"
  }'
<?php
$payload = [
    'api_user' => 'SEU_API_USER',
    'api_key'  => 'SUA_API_KEY',
    'to'       => [
        ['email' => 'email1@dominio.com', 'name' => 'Fulano1'],
        ['email' => 'email2@dominio.com', 'name' => 'Fulano2'],
        ['email' => 'email3@dominio.com', 'name' => 'Fulano3'],
    ],
    'from'     => ['name' => 'Minha Empresa', 'email' => 'contato@seudominio.com.br'],
    'subject'  => 'Comunicado Geral',
    'html'     => '<p>Mensagem para múltiplos destinatarios.</p>',
];

$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    to: [
      { email: 'email1@dominio.com', name: 'Fulano1' },
      { email: 'email2@dominio.com', name: 'Fulano2' },
      { email: 'email3@dominio.com', name: 'Fulano3' },
    ],
    from: { name: 'Minha Empresa', email: 'contato@seudominio.com.br' },
    subject: 'Comunicado Geral',
    html: '<p>Mensagem para múltiplos destinatarios.</p>',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/send', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'to': [
        {'email': 'email1@dominio.com', 'name': 'Fulano1'},
        {'email': 'email2@dominio.com', 'name': 'Fulano2'},
        {'email': 'email3@dominio.com', 'name': 'Fulano3'},
    ],
    'from': {'name': 'Minha Empresa', 'email': 'contato@seudominio.com.br'},
    'subject': 'Comunicado Geral',
    'html': '<p>Mensagem para múltiplos destinatarios.</p>',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "to": [
    {"email": "email1@dominio.com", "name": "Fulano1"},
    {"email": "email2@dominio.com", "name": "Fulano2"},
    {"email": "email3@dominio.com", "name": "Fulano3"}
  ],
  "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
  "subject": "Comunicado Geral",
  "html": "<p>Mensagem para múltiplos destinatarios.</p>"
}
Resposta de Sucesso
{
  "status": "ok",
  "message": "3 recipient(s)",
  "size": "2KB"
}

Envio com Anexos (Base64)

Envie anexos no array attachments — cada item com filename, type (MIME) e content em base64.

curl -X POST https://api.iagentesmtp.com.br/api/v3/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
    "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
    "subject": "Email com Anexo",
    "html": "<p>Segue documento em anexo.</p>",
    "attachments": [
      {"filename": "relatorio.pdf", "type": "application/pdf", "content": "JVBERi0xLjQKJ..."}
    ]
  }'
<?php
$payload = [
    'api_user'    => 'SEU_API_USER',
    'api_key'     => 'SUA_API_KEY',
    'to'          => [['email' => 'destinatario@email.com', 'name' => 'Fulano']],
    'from'        => ['name' => 'Minha Empresa', 'email' => 'contato@seudominio.com.br'],
    'subject'     => 'Email com Anexo',
    'html'        => '<p>Segue documento em anexo.</p>',
    'attachments' => [
        [
            'filename' => 'relatorio.pdf',
            'type'     => 'application/pdf',
            'content'  => base64_encode(file_get_contents('/caminho/para/relatorio.pdf')),
        ],
    ],
];

$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
echo curl_exec($ch);
import { readFileSync } from 'node:fs';

const res = await fetch('https://api.iagentesmtp.com.br/api/v3/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    to: [{ email: 'destinatario@email.com', name: 'Fulano' }],
    from: { name: 'Minha Empresa', email: 'contato@seudominio.com.br' },
    subject: 'Email com Anexo',
    html: '<p>Segue documento em anexo.</p>',
    attachments: [
      {
        filename: 'relatorio.pdf',
        type: 'application/pdf',
        content: readFileSync('./relatorio.pdf').toString('base64'),
      },
    ],
  }),
});

console.log(await res.json());
import base64
import requests

with open('/caminho/para/relatorio.pdf', 'rb') as f:
    conteudo = base64.b64encode(f.read()).decode()

res = requests.post('https://api.iagentesmtp.com.br/api/v3/send', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'to': [{'email': 'destinatario@email.com', 'name': 'Fulano'}],
    'from': {'name': 'Minha Empresa', 'email': 'contato@seudominio.com.br'},
    'subject': 'Email com Anexo',
    'html': '<p>Segue documento em anexo.</p>',
    'attachments': [
        {'filename': 'relatorio.pdf', 'type': 'application/pdf', 'content': conteudo},
    ],
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
  "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
  "subject": "Email com Anexo",
  "html": "<p>Segue documento em anexo.</p>",
  "attachments": [
    {"filename": "relatorio.pdf", "type": "application/pdf", "content": "JVBERi0xLjQKJ..."}
  ]
}
Resposta de Erro
{
  "status": "failed",
  "message": "invalid attachment format"
}

Envio com Template Cadastrado

Envie usando um template previamente cadastrado no painel: informe o token no campo templateid no lugar de html/text.

curl -X POST https://api.iagentesmtp.com.br/api/v3/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
    "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
    "subject": "Assunto do Email",
    "templateid": "TOKEN_DO_TEMPLATE"
  }'
<?php
$payload = [
    'api_user'   => 'SEU_API_USER',
    'api_key'    => 'SUA_API_KEY',
    'to'         => [['email' => 'destinatario@email.com', 'name' => 'Fulano']],
    'from'       => ['name' => 'Minha Empresa', 'email' => 'contato@seudominio.com.br'],
    'subject'    => 'Assunto do Email',
    'templateid' => 'TOKEN_DO_TEMPLATE',
];

$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    to: [{ email: 'destinatario@email.com', name: 'Fulano' }],
    from: { name: 'Minha Empresa', email: 'contato@seudominio.com.br' },
    subject: 'Assunto do Email',
    templateid: 'TOKEN_DO_TEMPLATE',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/send', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'to': [{'email': 'destinatario@email.com', 'name': 'Fulano'}],
    'from': {'name': 'Minha Empresa', 'email': 'contato@seudominio.com.br'},
    'subject': 'Assunto do Email',
    'templateid': 'TOKEN_DO_TEMPLATE',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "to": [{"email": "destinatario@email.com", "name": "Fulano"}],
  "from": {"name": "Minha Empresa", "email": "contato@seudominio.com.br"},
  "subject": "Assunto do Email",
  "templateid": "TOKEN_DO_TEMPLATE"
}
Resposta de Erro
{
  "status": "failed",
  "message": "template not found"
}

Envio Personalizado por Destinatario

Declare os valores de cada destinatario no objeto custom e use os placeholders no subject e no html. Cada destinatario recebe o conteúdo com os seus próprios valores.

curl -X POST https://api.iagentesmtp.com.br/api/v3/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "to": [
      {
        "email": "maria@empresa.com.br",
        "name": "Maria Silva",
        "custom": {"nome": "Maria", "empresa": "Empresa A", "codigo": "ABC123"}
      },
      {
        "email": "joao@empresa.com.br",
        "name": "Joao Santos",
        "custom": {"nome": "Joao", "empresa": "Empresa B", "codigo": "XYZ789"}
      }
    ],
    "from": {"name": "Suporte", "email": "contato@seudominio.com.br"},
    "subject": "Ola {{nome}}, sua conta na {{empresa}}",
    "html": "<p>Ola <strong>{{nome}}</strong>, seu código e: {{codigo}}</p>"
  }'
<?php
$payload = [
    'api_user' => 'SEU_API_USER',
    'api_key'  => 'SUA_API_KEY',
    'to'       => [
        [
            'email'  => 'maria@empresa.com.br',
            'name'   => 'Maria Silva',
            'custom' => ['nome' => 'Maria', 'empresa' => 'Empresa A', 'codigo' => 'ABC123'],
        ],
        [
            'email'  => 'joao@empresa.com.br',
            'name'   => 'Joao Santos',
            'custom' => ['nome' => 'Joao', 'empresa' => 'Empresa B', 'codigo' => 'XYZ789'],
        ],
    ],
    'from'     => ['name' => 'Suporte', 'email' => 'contato@seudominio.com.br'],
    'subject'  => 'Ola {{nome}}, sua conta na {{empresa}}',
    'html'     => '<p>Ola <strong>{{nome}}</strong>, seu código e: {{codigo}}</p>',
];

$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    to: [
      {
        email: 'maria@empresa.com.br',
        name: 'Maria Silva',
        custom: { nome: 'Maria', empresa: 'Empresa A', codigo: 'ABC123' },
      },
      {
        email: 'joao@empresa.com.br',
        name: 'Joao Santos',
        custom: { nome: 'Joao', empresa: 'Empresa B', codigo: 'XYZ789' },
      },
    ],
    from: { name: 'Suporte', email: 'contato@seudominio.com.br' },
    subject: 'Ola {{nome}}, sua conta na {{empresa}}',
    html: '<p>Ola <strong>{{nome}}</strong>, seu código e: {{codigo}}</p>',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/send', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'to': [
        {
            'email': 'maria@empresa.com.br',
            'name': 'Maria Silva',
            'custom': {'nome': 'Maria', 'empresa': 'Empresa A', 'codigo': 'ABC123'},
        },
        {
            'email': 'joao@empresa.com.br',
            'name': 'Joao Santos',
            'custom': {'nome': 'Joao', 'empresa': 'Empresa B', 'codigo': 'XYZ789'},
        },
    ],
    'from': {'name': 'Suporte', 'email': 'contato@seudominio.com.br'},
    'subject': 'Ola {{nome}}, sua conta na {{empresa}}',
    'html': '<p>Ola <strong>{{nome}}</strong>, seu código e: {{codigo}}</p>',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "to": [
    {
      "email": "maria@empresa.com.br",
      "name": "Maria Silva",
      "custom": {"nome": "Maria", "empresa": "Empresa A", "codigo": "ABC123"}
    },
    {
      "email": "joao@empresa.com.br",
      "name": "Joao Santos",
      "custom": {"nome": "Joao", "empresa": "Empresa B", "codigo": "XYZ789"}
    }
  ],
  "from": {"name": "Suporte", "email": "contato@seudominio.com.br"},
  "subject": "Ola {{nome}}, sua conta na {{empresa}}",
  "html": "<p>Ola <strong>{{nome}}</strong>, seu código e: {{codigo}}</p>"
}
Resposta de Sucesso
{
  "status": "ok",
  "message": "2 recipient(s)",
  "size": "3KB"
}

Histórico de Eventos

POST /history Consultar eventos de um destinatario

Consulta o histórico de eventos registrados para um destinatario (envios, 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
email string Sim Email do destinatario consultado

Exemplo

curl -X POST https://api.iagentesmtp.com.br/api/v3/history \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "email": "destinatario@email.com"
  }'
<?php
$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/history');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_user' => 'SEU_API_USER',
        'api_key'  => 'SUA_API_KEY',
        'email'    => 'destinatario@email.com',
    ]),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/history', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    email: 'destinatario@email.com',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/history', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'email': 'destinatario@email.com',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "email": "destinatario@email.com"
}
Resposta de Sucesso
{
  "status": "ok",
  "message": "history available",
  "records": 2,
  "email": "destinatario@email.com",
  "events": [...]
}
Resposta de Erro
{
  "status": "failed",
  "message": "email not found"
}

Domínios de Envio

Cadastre e remova domínios de envio via API. Ao cadastrar um domínio, a resposta retorna os registros DNS que devem ser configurados (veja Configuração DNS).

Cadastrar Domínio

POST /domain/create Cadastrar novo domínio para envio 
curl -X POST https://api.iagentesmtp.com.br/api/v3/domain/create \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "domain": "seudominio.com.br"
  }'
<?php
$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/domain/create');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_user' => 'SEU_API_USER',
        'api_key'  => 'SUA_API_KEY',
        'domain'   => 'seudominio.com.br',
    ]),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/domain/create', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    domain: 'seudominio.com.br',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/domain/create', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'domain': 'seudominio.com.br',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "domain": "seudominio.com.br"
}
Resposta de Sucesso
{
  "status": "ok",
  "domain": "seudominio.com.br",
  "message": "domain registered",
  "dns": {...}
}
Resposta de Erro
{
  "status": "failed",
  "message": "domain already exists"
}

Remover Domínio

POST /domain/delete Remover domínio 
curl -X POST https://api.iagentesmtp.com.br/api/v3/domain/delete \
  -H "Content-Type: application/json" \
  -d '{
    "api_user": "SEU_API_USER",
    "api_key": "SUA_API_KEY",
    "domain": "seudominio.com.br"
  }'
<?php
$ch = curl_init('https://api.iagentesmtp.com.br/api/v3/domain/delete');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'api_user' => 'SEU_API_USER',
        'api_key'  => 'SUA_API_KEY',
        'domain'   => 'seudominio.com.br',
    ]),
]);
echo curl_exec($ch);
const res = await fetch('https://api.iagentesmtp.com.br/api/v3/domain/delete', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_user: 'SEU_API_USER',
    api_key: 'SUA_API_KEY',
    domain: 'seudominio.com.br',
  }),
});

console.log(await res.json());
import requests

res = requests.post('https://api.iagentesmtp.com.br/api/v3/domain/delete', json={
    'api_user': 'SEU_API_USER',
    'api_key': 'SUA_API_KEY',
    'domain': 'seudominio.com.br',
})

print(res.json())
{
  "api_user": "SEU_API_USER",
  "api_key": "SUA_API_KEY",
  "domain": "seudominio.com.br"
}
Resposta de Sucesso
{
  "status": "ok",
  "message": "domain removed"
}
Resposta de Erro
{
  "status": "failed",
  "message": "domain not found"
}

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

{
  "Email": "destinatario@email.com",
  "Data": "18/08/2026 18:03:22",
  "Tipo": "enviado",
  "TransacaoID": "28CLI27881843096a84c89acb6abSMTP8132",
  "Assunto": "Envio de teste IAGENTESMTP - 18/08/2026 18:03:22",
  "Descricao": "",
  "CampanhaID": "",
  "Log": "",
  "IP": "",
  "UA": ""
}
{
  "Email": "destinatario@email.com",
  "Data": "18/08/2026 18:03:24",
  "Tipo": "entregue",
  "TransacaoID": "28CLI27881843096a84c89acb6abSMTP8132",
  "Assunto": "Envio de teste IAGENTESMTP - 18/08/2026 18:03:22",
  "Descricao": "e-mail entregue no provedor",
  "CampanhaID": "",
  "Log": "2026-08-18 18:03:23 31B3DA6947: uid=1000 from=retorno@seudominio.com.br\n2026-08-18 18:03:24 31B3DA6947: to=destinatario@email.com, relay=powersmtp.iagente.net.br[...]:25, delay=0.92, dsn=2.0.0, status=sent (250 2.0.0 Ok: queued as 43BD0C18C5)\n2026-08-18 18:03:24 31B3DA6947: removed\n",
  "IP": "",
  "UA": ""
}
{
  "Email": "email-inexistente@dominio.com.br",
  "Data": "18/08/2026 18:16:33",
  "Tipo": "bounce",
  "TransacaoID": "28CLI27881914876a84cbb020659SMTP84561123335",
  "Assunto": "Envio de teste IAGENTESMTP - 18/08/2026 18:16:31",
  "Descricao": "endereco inexistente",
  "CampanhaID": "",
  "Log": "smtp; 550 5.1.1 email-inexistente@dominio.com.br: Recipient address rejected: User unknown in virtual mailbox table",
  "IP": "",
  "UA": ""
}

Campos do Webhook

Campo Tipo Descrição
Email string Email do destinatario
Data string Data/hora do evento (dd/mm/aaaa hh:mm:ss)
Tipo string Tipo do evento
TransacaoID string ID único da transação de envio
Assunto string Assunto do email
Descricao string Descrição legível do evento (ex.: "e-mail entregue no provedor"; motivo em falha e bounce)
CampanhaID string ID da campanha, quando o envio pertence a uma
Log string Log SMTP bruto da transação no servidor de envio (linhas separadas por \n)
IP string IP do destinatario (em eventos de leitura/clique)
UA string User agent do destinatario (em eventos de leitura/clique)

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

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? Abra um chamado para o suporte técnico ou acesse a Central de Ajuda.

Documentação

Outras APIs do ecossistema

Ver todas →
API WhatsApp e SDR — SDRBOT.ai

Mensagens WhatsApp Business, templates Meta, leads e webhooks.

Ver documentação → API Email Marketing — IAGENTEmail

Contatos, grupos e listas com importação em massa e respostas em JSON.

Ver documentação → API SMS — IAGENTEsms

REST v2 com Bearer e escopos: envio, lotes, callbacks e status.

Ver documentação →