"
msg["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click"
```
Pela API, os dois vão no campo `headers` do [envio de mensagem](/api/referencia/operations/messages/post/).
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* A iPORTO assina os dois cabeçalhos com o DKIM do seu domínio. Não há nada a ligar no painel.
* O botão aparece quando o provedor decide mostrar. Os cabeçalhos são o requisito, não a garantia: cada provedor também pesa o volume e o histórico do remetente.
* Quando o destinatário clica, o provedor faz o `POST` direto no seu endereço — o pedido não passa pela iPORTO. Quem registra o descadastro é o seu sistema; para bloquear também do lado da iPORTO, inclua o endereço na [lista de supressão](/ajuda/smtp/lista-de-supressao/).
* Gmail e Yahoo pedem que o descadastro seja atendido em até dois dias.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ----------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| O botão **Cancelar inscrição** não aparece | O provedor ainda não mostra para o seu remetente, ou falta um dos cabeçalhos | Confira o original: com os dois cabeçalhos no `h=` e DKIM `PASS`, a parte do seu lado está feita |
| `List-Unsubscribe-Post` não aparece no original | O sistema não enviou o cabeçalho, ou o nome está escrito diferente | Confira o nome exato e se o cabeçalho é incluído em todas as mensagens |
| DKIM `FAIL` ou sem assinatura | O `From` é de um domínio não cadastrado, ou os registros DNS não estão publicados | Use um remetente do domínio cadastrado e confira [os registros DNS](/ajuda/smtp/publicar-os-registros-dns/) |
| O clique não descadastra | O endereço só aceita `GET`, pede login ou redireciona | Aceite `POST` sem login e responda `200`, sem redirecionar |
| Contatos descadastrados sem terem clicado | O endereço descadastra no `GET`, e filtros antispam abrem os links da mensagem | Descadastre só no `POST`; no `GET`, peça confirmação |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Impedir envios para um endereço (lista de supressão)](/ajuda/smtp/lista-de-supressao/)
* [Acompanhar as métricas e a pontuação do domínio](/ajuda/smtp/acompanhar-metricas-e-score/)
# Conectar seu sistema ao servidor SMTP
> Host, porta e criptografia para configurar o envio no seu sistema, com exemplos em PHP, Node.js e Python.
Com o domínio cadastrado e uma credencial criada, falta configurar o seu sistema — loja, ERP, CRM ou aplicação própria — para enviar pelo servidor SMTP da iPORTO.
Usa WordPress, Joomla, Mautic ou Supabase?
Siga o guia da sua plataforma, com o nome de cada campo na tela dela: [WordPress](/ajuda/smtp/plataformas/wordpress/), [Joomla](/ajuda/smtp/plataformas/joomla/), [Mautic](/ajuda/smtp/plataformas/mautic/) ou [Supabase](/ajuda/smtp/plataformas/supabase/). Para um app feito no Lovable, veja [Integrar com Lovable](/api/guias/lovable/).
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Um domínio cadastrado e uma credencial — veja [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/).
* A rede de onde o seu sistema envia precisa permitir conexões de saída na porta **587** — ou, se ela estiver bloqueada, na **465**.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do SMTP, abra o domínio em **Infraestrutura → Domínios (SMTP)**.
2. Na aba **Credenciais**, o card **Servidor de Conexão** traz os dados de conexão:
| Campo | Valor |
| ------------------------ | ---------------------------------------------------- |
| **Host (Servidor SMTP)** | `smtp-avancado.com` |
| **Porta** | `587` |
| **Criptografia** | TLS (STARTTLS) |
| **Usuário** | a credencial completa, como `loja@suaempresa.com.br` |
| **Senha** | a senha mostrada no card da credencial |
Se a porta 587 estiver bloqueada na sua rede, use a **465** com **SSL** — a conexão já começa criptografada, sem STARTTLS. Os demais dados não mudam.
3. Configure esses dados no seu sistema. O remetente (`From`) deve ser um endereço do domínio cadastrado.
4. Faça um envio de teste para uma caixa sua e confira em [Histórico de envio](/ajuda/smtp/consultar-o-historico-de-envio/).
A aba **Instalação** do domínio traz exemplos prontos para Laravel, Nodemailer, Python e PHPMailer, já com os dados do seu domínio.
## Exemplos
[Seção intitulada “Exemplos”](#exemplos)
Troque o usuário e a senha pelos valores do seu painel.
**PHP (PHPMailer)**
```php
$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'smtp-avancado.com';
$mail->SMTPAuth = true;
$mail->Username = 'loja@suaempresa.com.br';
$mail->Password = 'SENHA_DO_PAINEL';
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->Port = 587;
$mail->setFrom('loja@suaempresa.com.br', 'Sua Empresa');
$mail->addAddress('cliente@exemplo.com');
$mail->isHTML(true);
$mail->Subject = 'Seu pedido foi confirmado';
$mail->Body = 'Olá! Recebemos o seu pedido.
';
$mail->send();
```
**Node.js (Nodemailer)**
```js
const nodemailer = require('nodemailer');
const transporter = nodemailer.createTransport({
host: 'smtp-avancado.com',
port: 587,
secure: false, // a criptografia é negociada por STARTTLS na porta 587
auth: { user: 'loja@suaempresa.com.br', pass: 'SENHA_DO_PAINEL' },
});
await transporter.sendMail({
from: '"Sua Empresa" ',
to: 'cliente@exemplo.com',
subject: 'Seu pedido foi confirmado',
html: 'Olá! Recebemos o seu pedido.
',
});
```
**Python (smtplib)**
```python
import smtplib
from email.message import EmailMessage
msg = EmailMessage()
msg["Subject"] = "Seu pedido foi confirmado"
msg["From"] = "Sua Empresa "
msg["To"] = "cliente@exemplo.com"
msg.set_content("Olá! Recebemos o seu pedido.")
with smtplib.SMTP("smtp-avancado.com", 587, timeout=30) as smtp:
smtp.starttls()
smtp.login("loja@suaempresa.com.br", "SENHA_DO_PAINEL")
smtp.send_message(msg)
```
Para testar só a conexão e o TLS, pela linha de comando:
```bash
openssl s_client -starttls smtp -connect smtp-avancado.com:587
```
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
Cada e-mail aceito pelo servidor entra no **Histórico de Envio**, com o status da entrega. Aceito pelo servidor não quer dizer entregue na caixa de entrada: o destino ainda pode recusar, adiar ou filtrar a mensagem — e é o histórico que mostra o que aconteceu.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Tempo esgotado ao conectar | A porta 587 está bloqueada na sua rede ou no seu provedor de hospedagem | Use a porta 465 com SSL; se ela também estiver bloqueada, libere a saída no firewall ou peça ao provedor |
| Erro de TLS / handshake | Biblioteca ou OpenSSL desatualizado, ou o sistema tentou SSL direto na 587 | Na 587, use STARTTLS (no Nodemailer, `secure: false`); SSL direto só na 465 (no Nodemailer, `secure: true`); atualize a biblioteca |
| `535 Incorrect authentication data` | Usuário ou senha errados | Use o endereço completo como usuário e copie a senha pelo botão do painel |
| `550 Relaying denied` / `Authentication required` | O sistema está enviando sem autenticar | Ative a autenticação SMTP (LOGIN/PLAIN) na configuração do sistema |
| O e-mail sai mas não aparece no histórico | O sistema está usando outro servidor de envio | Confira o host configurado no sistema |
Para falhas depois da conexão — e-mail recusado pelo destino, bounce, spam —, veja [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/).
# Consultar e exportar o histórico de envio
> Encontrar um e-mail enviado, ver o que aconteceu com ele e exportar os resultados.
O histórico mostra cada e-mail que passou pelo SMTP e o que aconteceu com ele: se foi entregue, recusado, adiado ou filtrado — com a resposta do servidor de destino. É o primeiro lugar a olhar quando alguém diz que “não recebeu”.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do SMTP, vá em **Envios → Histórico de Envio**.
2. Para achar um e-mail específico, digite o **e-mail do destinatário** na busca e clique em **Buscar**.
3. Para refinar, abra **Filtros Avançados**:
* **Status de Entrega** — por exemplo, só **Não entregue** ou **Com bounce**;
* **Código de Rastreamento**, **Message ID** ou **Message ID Relay** — para achar uma mensagem exata a partir dos registros do seu sistema;
* **Tags** — separe várias por vírgula;
* **Período** — data inicial e final;
* **Apenas com Hard Bounce**, **Apenas com Soft Bounce** ou **Apenas com Spam Trap**.
Clique em **Aplicar Filtros**.
4. Clique numa linha para abrir os detalhes do e-mail.
## O que você vê no detalhe
[Seção intitulada “O que você vê no detalhe”](#o-que-você-vê-no-detalhe)
| Aba | O que mostra |
| ------------------ | --------------------------------------------------------------------------------------- |
| **Visão Geral** | Remetente, destinatários, tamanho, tags, servidor e status — e quando o registro expira |
| **Cabeçalhos** | Os cabeçalhos completos da mensagem |
| **Log de Entrega** | Cada tentativa de entrega, com a **Resposta do Servidor** de destino |
| **Bounces** | Falhas permanentes (hard bounce) e temporárias (soft bounce) |
## Exportar
[Seção intitulada “Exportar”](#exportar)
1. Aplique os filtros que quiser.
2. Clique em **Exportar** e escolha **Todos os envios**, **Soft Bounce**, **Hard Bounce** ou **Spam Trap**.
3. A exportação é preparada em segundo plano. Acompanhe em **Exportações**, no menu: quando o status for **Concluído**, clique em **Baixar**.
O arquivo é um CSV com os envios que batem com os filtros aplicados.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
Os registros do histórico têm prazo de retenção — o detalhe de cada e-mail mostra quando ele expira. Se precisar guardar por mais tempo, exporte.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Não acho um e-mail que o sistema diz ter enviado | O sistema enviou por outro servidor, ou o período do filtro não inclui o envio | Amplie o **Período**; confira o host configurado no sistema |
| O e-mail aparece como **Na fila** ou **Em entrega** por muito tempo | O destino está adiando a entrega (soft bounce) e o servidor está tentando de novo | Abra o detalhe e veja a **Resposta do Servidor** no **Log de Entrega** |
| A exportação fica em **Processando** | Volumes grandes levam mais tempo | Aguarde e atualize a página de **Exportações** |
| A exportação **Falhou** | Erro ao gerar o arquivo | Gere de novo; se repetir, abra um chamado |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
# Criar uma credencial SMTP (usuário e senha)
> Gerar um usuário e senha para o seu sistema se conectar ao SMTP, testar e trocar a senha.
A credencial é o usuário e a senha que o seu sistema usa para se conectar ao servidor SMTP da iPORTO. Cada domínio pode ter várias — uma por sistema, por exemplo, para saber de onde veio cada envio e poder desligar uma sem afetar as outras.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
O domínio precisa estar cadastrado — veja [Adicionar um domínio de envio](/ajuda/smtp/adicionar-um-dominio/). Todo domínio já nasce com a credencial `no-reply@` do próprio domínio; se ela basta, você não precisa criar outra.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do SMTP, vá em **Infraestrutura → Domínios (SMTP)** e abra o domínio.
2. Na aba **Credenciais**, clique em **Nova credencial**.
3. Em **Usuário SMTP**, digite a parte antes do `@` — por exemplo, `loja` para `loja@suaempresa.com.br`. A tela mostra a credencial completa enquanto você digita.
4. Clique em **Criar**.
Regras do usuário: de 1 a 25 caracteres, só letras minúsculas, números, ponto (`.`), sublinhado (`_`) e hífen (`-`). Ele não pode começar nem terminar com esses símbolos, nem repeti-los em sequência.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* A senha é **gerada automaticamente** — você não escolhe. Ela aparece no card da credencial, na aba **Credenciais**, em **Senha**, com um botão para copiar. Copie exatamente como está: maiúsculas e minúsculas fazem diferença.
* Use o botão **Testar** no card para conferir se a credencial conecta. A tela responde com “Conexão SMTP testada com sucesso!” ou com a falha.
* O **Usuário (Username)** que o seu sistema deve usar é o endereço completo, como `loja@suaempresa.com.br`.
Para trocar a senha
Não há um botão de gerar senha nova. Para trocar — porque a senha vazou, por exemplo —, clique em **Excluir** no card e crie a credencial de novo com o **mesmo usuário**. Ela volta com uma senha nova. Atualize o seu sistema logo em seguida: até lá, os envios com a senha antiga falham.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| “Esta conta já está em uso.” | Já existe uma credencial com esse usuário neste domínio | Use a existente, ou escolha outro nome |
| “Você atingiu o limite de contas permitidas para o seu plano…” | O plano permite um número de credenciais e todas estão em uso | Exclua uma que não usa mais, ou mude de plano |
| O nome não é aceito | Caractere fora da regra (maiúscula, espaço, acento, símbolo no começo ou no fim) | Use só letras minúsculas, números, `.`, `_` e `-` |
| **Testar** falha | O **Status** da credencial está **Inativo**, ou o domínio está bloqueado | Confira o **Status** da credencial e o status do domínio na lista de domínios |
| O seu sistema recebe “autenticação inválida” | A senha foi copiada errada, ou o usuário foi informado sem o `@domínio` | Copie a senha pelo botão da tela e use o endereço completo como usuário |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Conectar seu sistema ao servidor SMTP](/ajuda/smtp/conectar-seu-sistema/)
# Entender por que um e-mail não foi entregue
> O que significa cada status do histórico, como ler a resposta do servidor de destino e qual artigo resolve cada tipo de recusa.
Quando um e-mail não chega, o histórico de envio diz o motivo — no status e, principalmente, na resposta do servidor de destino. Este artigo ajuda a ler essa resposta e a encontrar o artigo que trata o seu caso.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Em **Histórico de Envio**, encontre o e-mail (busque pelo destinatário).
2. Abra o e-mail e vá na aba **Log de Entrega**. Há um bloco por destinatário, com o campo **Bounce** (**Nenhum**, **Hard Bounce** ou **Soft Bounce**) e a **Resposta do servidor de destino** — a mensagem que o servidor do destinatário devolveu.
3. Se o título do bloco for **Motivo do descarte**, a mensagem nem saiu da iPORTO: veja [Por que uma mensagem é descartada antes do envio](#por-que-uma-mensagem-%C3%A9-descartada-antes-do-envio).
4. Se for **Resposta do servidor de destino**, leia a resposta como em [Ler a resposta do servidor de destino](#ler-a-resposta-do-servidor-de-destino) e siga para o artigo da família do erro.
## Os status do histórico
[Seção intitulada “Os status do histórico”](#os-status-do-histórico)
| Status | O que quer dizer |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Na fila** | Aceito pela iPORTO, aguardando a primeira tentativa |
| **Em entrega** | Em tentativa de entrega — inclusive quando o destino pediu para tentar mais tarde |
| **Processada com sucesso** | O servidor de destino aceitou a mensagem |
| **Com bounce** | O destino recusou. Veja se foi hard ou soft bounce, abaixo |
| **Descartada antes do envio** | Nenhum destinatário recebeu. A mensagem foi interrompida por uma regra da plataforma antes da entrega |
| **Parcialmente descartada** | Parte dos destinatários foi descartada antes de sair; os demais seguiram para entrega |
| **Spam trap** | O destinatário é uma armadilha de spam — um endereço usado para identificar listas de baixa qualidade |
| **Não entregue** | Não foi possível entregar depois das tentativas |
### Por que uma mensagem é descartada antes do envio
[Seção intitulada “Por que uma mensagem é descartada antes do envio”](#por-que-uma-mensagem-é-descartada-antes-do-envio)
Quando o status é **Descartada antes do envio** ou **Parcialmente descartada**, a mensagem não chegou ao servidor de destino: ela foi interrompida aqui. Abra a mensagem no histórico e o motivo aparece **por destinatário**, em **Motivo do descarte**.
| Motivo | O que fazer |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Pontuação do domínio abaixo do mínimo** | Nenhuma mensagem é enviada nesse nível. Veja [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/) |
| **Pontuação do domínio abaixo do exigido pelo destino** | Aquele destino exige mais que a sua pontuação atual; os outros continuam recebendo |
| **Registro SPF não publicado** | O destino exige autenticação do remetente. Veja [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/) |
| **Endereço na lista de supressão** | O endereço está bloqueado. Confira o motivo na [lista de supressão](/ajuda/smtp/lista-de-supressao/) |
A pontuação é a causa mais comum, e não se resolve na lista de supressão
Se o motivo for a **pontuação do domínio**, apagar bloqueios da lista de supressão não ajuda — e tende a piorar, porque a lista é o que impede o reenvio para endereços que já deram erro. Os bloqueios excluídos não podem ser recuperados.
Aceito não é o mesmo que caixa de entrada
**Processada com sucesso** quer dizer que o servidor de destino aceitou a mensagem. Daí em diante, é o provedor (Gmail, Outlook…) que decide se ela vai para a caixa de entrada, para promoções ou para o spam — e essa decisão não volta para o histórico.
## Hard bounce e soft bounce
[Seção intitulada “Hard bounce e soft bounce”](#hard-bounce-e-soft-bounce)
* **Hard bounce** é uma recusa **permanente**: o endereço não existe, o domínio não existe, a caixa foi desativada. Tentar de novo não resolve. Tire o endereço da sua lista.
* **Soft bounce** é uma recusa **temporária**: caixa cheia, servidor indisponível, limite de recebimento atingido. O servidor tenta de novo sozinho; se continuar falhando, o e-mail termina como não entregue.
O destinatário que termina com bounce entra sozinho na [lista de supressão](/ajuda/smtp/lista-de-supressao/), com o motivo **Hard Bounce detectado no envio de e-mail** (vale 365 dias) ou **Soft Bounce detectado no envio de e-mail** (vale 7 dias). O motivo traz o ID de Histórico da mensagem que causou o bloqueio. Quando a causa foi só tempo esgotado na conexão com o destino, o endereço não é bloqueado.
Quem marca uma mensagem como spam — quando o provedor avisa — também entra na lista de supressão sozinho. Envios seguintes para esse endereço aparecem como **Parcialmente descartada** no histórico, com o motivo **Endereço na lista de supressão**.
## Ler a resposta do servidor de destino
[Seção intitulada “Ler a resposta do servidor de destino”](#ler-a-resposta-do-servidor-de-destino)
A resposta é uma linha só, e cada trecho dela diz uma coisa. Um exemplo real, com o endereço trocado:
```plaintext
** cliente@exemplo.com.br R=dnslookup T=remote_smtp H=mx.exemplo.com.br [200.0.0.10] X=TLSv1.2:...: SMTP error from remote mail server after RCPT TO:: 550 5.1.1 : Recipient address rejected: User unknown in virtual mailbox table
```
| Trecho | O que diz |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `**` no começo | O destino **recusou** este destinatário |
| `==` no começo | A entrega foi **adiada**: o destino pediu para tentar mais tarde, ou não respondeu. Uma nova tentativa é feita sozinha |
| `H=mx.exemplo.com.br` | Qual servidor respondeu — é por ele que se sabe o provedor: `google.com` é Gmail ou Google Workspace; `outlook.com` é Microsoft (Outlook, Hotmail, Microsoft 365) |
| Sem `H=` | Nenhum servidor do destino chegou a ser contatado — o problema está no domínio do destinatário |
| `after RCPT TO` | O destino recusou o **endereço**, antes de receber a mensagem |
| `after end of data` | O destino recebeu a mensagem inteira e recusou o **conteúdo**: cabeçalho, autenticação ou reputação |
| `550 5.1.1` | O código. Primeiro dígito `4` é temporário; `5` é definitivo. O número do meio (`5.1.1`) diz a família do erro |
| O texto depois do código | A explicação do provedor. Cada um escreve à sua maneira, e é ela que decide o caso |
Os trechos `R=`, `T=` e `X=` são de roteamento e criptografia e podem ser ignorados.
## Qual artigo resolve o seu caso
[Seção intitulada “Qual artigo resolve o seu caso”](#qual-artigo-resolve-o-seu-caso)
| A resposta fala em | Família | Artigo |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `5.1.1`, `does not exist`, `User unknown`, `mailbox unavailable`, `Recipient not found` | O endereço não existe | [Remover endereços que não existem](/ajuda/smtp/erros-de-entrega/endereco-nao-existe/) |
| `Unrouteable address`, `no SMTP service`, `Relay access denied` | O domínio do destinatário não recebe e-mail | [Tratar um domínio que não recebe e-mail](/ajuda/smtp/erros-de-entrega/dominio-nao-recebe-email/) |
| `5.7.26`, `5.7.27`, `5.7.23`, `5.7.509`, `unauthenticated`, SPF, DKIM, DMARC | O destino não reconheceu o remetente | [Corrigir uma recusa por autenticação](/ajuda/smtp/erros-de-entrega/autenticacao-spf-dkim-dmarc/) |
| `not RFC 5322 compliant`, `From: header`, `Message-ID`, cabeçalho duplicado | A mensagem saiu fora do padrão | [Corrigir uma recusa pelo formato da mensagem](/ajuda/smtp/erros-de-entrega/formato-da-mensagem/) |
| `==` no começo, códigos `4xx`, `Try again later`, `rate limited`, `Connection timed out`, caixa cheia | O destino adiou o recebimento | [Lidar com entregas adiadas pelo destino](/ajuda/smtp/erros-de-entrega/entrega-adiada/) |
| `554` / `message rejected as spam`, `likely unsolicited` | Conteúdo, links ou reputação do remetente | Revise o conteúdo e os links; confira a saúde do domínio em [Métricas e score](/ajuda/smtp/acompanhar-metricas-e-score/) |
| Menção a *blocklist*, *blacklist* ou Spamhaus | O IP ou o domínio de envio está numa lista de bloqueio | Abra um chamado com o **Message ID** e a resposta completa |
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ---------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Muitos hard bounces numa campanha | Lista desatualizada ou comprada | Valide a lista com o [Validador de E-mail](/ajuda/validador-de-email/validar-uma-lista/) antes do próximo envio |
| Tudo **Processada com sucesso**, mas o cliente não recebeu | A mensagem foi para o spam ou para outra aba no provedor | Peça ao destinatário para procurar no spam; revise o DNS e o conteúdo |
| A resposta do servidor não se encaixa em nenhuma família | Cada provedor escreve à sua maneira | Abra um chamado com o **Message ID** e a resposta completa |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Impedir envios para um endereço (lista de supressão)](/ajuda/smtp/lista-de-supressao/)
* [Acompanhar as métricas e a saúde do domínio](/ajuda/smtp/acompanhar-metricas-e-score/)
# Corrigir uma recusa por autenticação (SPF, DKIM, DMARC)
> Como reconhecer quando o destino recusou porque não conseguiu confirmar o remetente, e o que conferir no DNS e no remetente da mensagem.
O servidor de destino recebeu a mensagem, mas não conseguiu confirmar que ela saiu de quem diz ter enviado. Gmail, Microsoft e Yahoo exigem essa confirmação — SPF, DKIM e DMARC — e recusam ou limitam o que não passa. A correção é sua, no DNS do domínio ou no remetente da mensagem, e vale para todos os destinatários de uma vez.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Tenha acesso ao painel de DNS do domínio de envio (registro.br, Cloudflare, sua hospedagem…).
* Saiba onde o seu sistema define o remetente (`From`) das mensagens.
## Como reconhecer
[Seção intitulada “Como reconhecer”](#como-reconhecer)
Em **Histórico de Envio → (o e-mail) → Log de Entrega**, a resposta vem `after end of data` e cita autenticação, SPF, DKIM ou DMARC:
| Provedor | Resposta típica | O que não passou |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Gmail | `550-5.7.26 This email has been blocked because the sender is unauthenticated` | Nem SPF nem DKIM |
| Gmail | `550-5.7.26 Unauthenticated email from is not accepted due to domain's DMARC policy` | DMARC |
| Gmail | `550-5.7.27 This message was blocked because it didn't pass SPF authentication` | SPF |
| Gmail | `550-5.7.30 This message was blocked because it didn't pass DKIM authentication` | DKIM |
| Gmail | `5.7.32 … the From: header (RFC5322) in this message isn't aligned …` | O domínio do `From` não é o domínio autenticado |
| Gmail (temporário) | `421-4.7.26`, `421-4.7.27`, `421-4.7.30` ou `421-4.7.32 … rate limited because …` | Os mesmos casos acima: o Gmail ainda aceita, mas limita, e tenta de novo depois |
| Microsoft 365 | `550 5.7.23 The message was rejected because of Sender Policy Framework violation` | SPF |
| Microsoft 365 | `550 5.7.509 Access denied, sending domain … does not pass DMARC verification and has a DMARC policy of reject` | DMARC |
| Yahoo e AOL | `553` ou `554`, citando autenticação ou DMARC | SPF, DKIM ou DMARC |
Outlook.com e Hotmail
A Microsoft exige SPF, DKIM e DMARC de quem envia mais de 5 mil mensagens por dia para endereços Outlook.com, Hotmail e Live. Hoje a mensagem que não cumpre vai para o lixo eletrônico, e a Microsoft anunciou que passará a recusá-la com o código `5.7.515`.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Anote o que a resposta cita: SPF, DKIM, DMARC, `unauthenticated` ou `aligned`.
2. No painel do SMTP, vá em **Infraestrutura → Domínios (SMTP)**, abra o domínio e, na aba **DNS**, clique em **Verificar DNS**. SPF, DKIM e DMARC precisam aparecer como **Verificado**. O que estiver **Não verificado** se corrige como em [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/).
3. Confira o remetente da mensagem recusada: em **Histórico de Envio**, abra o e-mail e vá na aba **Cabecalhos**. Na linha `From:`, o endereço precisa ser do domínio que você cadastrou e verificou. `loja@gmail.com`, `contato@outlook.com` ou um subdomínio não cadastrado (`news.suaempresa.com.br`) não passam no DMARC, por mais que o DNS do seu domínio esteja certo.
4. Corrija conforme a tabela:
| O que você encontrou | O que fazer |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| SPF **Não verificado**, ou dois registros TXT começando com `v=spf1` | Deixe um registro SPF só, com o `include` da iPORTO — veja [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/) |
| SPF com muitos `include` de outros serviços | O SPF aceita no máximo 10 consultas de DNS; acima disso ele falha inteiro. Tire os `include` de serviços que você não usa mais |
| DKIM **Não verificado** | Publique de novo o registro `mail._domainkey`, copiando o valor inteiro da tela |
| `From` de outro domínio | Troque o remetente no seu sistema para um endereço do domínio cadastrado — veja [Conectar o seu sistema](/ajuda/smtp/conectar-seu-sistema/) |
| Tudo **Verificado** e `From` correto | Alguém pode ter mudado o DNS depois do envio. Clique em **Verificar DNS** de novo e compare com o que está publicado hoje |
5. Envie uma mensagem de teste para um endereço seu no Gmail e confira o resultado no **Histórico de Envio**.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* A correção vale para os próximos envios. As mensagens já recusadas não são reenviadas sozinhas: reenvie pelo seu sistema.
* Os destinatários recusados podem ter entrado na [lista de supressão](/ajuda/smtp/lista-de-supressao/) — por 365 dias se o campo **Bounce** mostrou **Hard Bounce**, por 7 dias se mostrou **Soft Bounce**. Como o problema era do remetente, e não deles, exclua **só** esses bloqueios antes de reenviar: o motivo de cada um traz o ID de Histórico da mensagem que o criou.
* Com SPF e DKIM publicados, a pontuação do domínio também se recupera — veja [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/).
Não esvazie a lista de supressão inteira
Exclua só os bloqueios das mensagens recusadas por autenticação. Os outros impedem o reenvio para endereços que realmente não recebem, e um bloqueio excluído não pode ser recuperado.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Tudo **Verificado** no painel, e o Gmail continua recusando por SPF | O DNS ainda está propagando, ou o seu provedor de DNS guarda a versão antiga | Espere algumas horas e verifique de novo; durante a configuração, use TTL baixo |
| Só um sistema seu é recusado; os outros entregam | Esse sistema usa outro remetente no `From` | Confira a aba **Cabecalhos** de uma mensagem dele e ajuste o remetente |
| A recusa cita DMARC com `p=reject`, e o SPF e o DKIM estão verificados | O `From` é de um domínio diferente do autenticado | Use no `From` um endereço do domínio cadastrado |
| Mudei o DMARC para `reject` e as recusas começaram | Algum envio do domínio ainda não está autenticado | Volte para `p=none` até todos os sistemas que enviam pelo domínio estarem configurados |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
# Tratar um domínio que não recebe e-mail
> O que fazer quando o domínio do destinatário não existe, não tem servidor de e-mail ou aponta para um servidor que não o aceita.
Aqui o problema não é o endereço, é tudo o que vem depois do `@`: o domínio do destinatário não existe, não tem servidor de e-mail publicado ou aponta para um servidor que não o aceita. Nenhuma mensagem para esse domínio é entregue até que o dono dele corrija o DNS.
## Como reconhecer
[Seção intitulada “Como reconhecer”](#como-reconhecer)
Em **Histórico de Envio → (o e-mail) → Log de Entrega**, a resposta costuma vir **sem `H=`** — sinal de que nenhum servidor do destino chegou a ser contatado.
| Resposta | O que quer dizer |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Unrouteable address` | O domínio não existe, ou não publica nenhum servidor para receber e-mail |
| `an MX or SRV record indicated no SMTP service` | O domínio declara no DNS que **não recebe** e-mail |
| `554 5.7.1 … Relay access denied` | O servidor apontado no DNS do destinatário não aceita mais e-mail para esse domínio — típico de quem trocou de provedor de e-mail e deixou o DNS antigo |
| `550 5.4.1 Relay Access Denied` (Microsoft 365) | O mesmo caso, num domínio hospedado na Microsoft |
| `Connection timed out`, sempre no mesmo domínio | O servidor do destinatário está fora do ar. Veja [Lidar com entregas adiadas pelo destino](/ajuda/smtp/erros-de-entrega/entrega-adiada/) |
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Confira a grafia do domínio na resposta: `gmial.com`, `hotmal.com`, `outlok.com`, `yahoo.com.br.br`, `.com` faltando o `.br`. Domínio digitado errado é a causa mais comum de `Unrouteable address`.
2. Se foi erro de digitação, corrija o endereço no cadastro do seu sistema.
3. Se a grafia está certa, o problema é do lado do destinatário — o domínio expirou, foi desativado ou mudou de provedor. Não há configuração na iPORTO que resolva. Avise o destinatário por outro canal (telefone, WhatsApp) e peça um endereço que funcione.
4. Se vários contatos usam esse domínio e ele não vai voltar, bloqueie o domínio inteiro na [lista de supressão](/ajuda/smtp/lista-de-supressao/), com o **Tipo de Bloqueio** em **Domínio**.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* O destinatário entra sozinho na [lista de supressão](/ajuda/smtp/lista-de-supressao/): por 365 dias se o campo **Bounce** mostrou **Hard Bounce**, por 7 dias se mostrou **Soft Bounce**.
* Envios seguintes para ele aparecem como **Parcialmente descartada**, com o motivo **Endereço na lista de supressão**.
* Se o destinatário corrigir o DNS do domínio, exclua o bloqueio na lista de supressão para voltar a enviar antes de ele expirar.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Um domínio que recebia bem passou a recusar com `Relay access denied` | O destinatário migrou o e-mail e o DNS ainda aponta para o provedor antigo | Avise o destinatário; quando ele corrigir o DNS, exclua o bloqueio e reenvie |
| O destinatário diz que recebe e-mail normalmente | O DNS dele mudou depois da tentativa, ou a falha foi momentânea | Exclua o bloqueio na lista de supressão e reenvie; se recusar de novo, mande a resposta completa ao suporte de e-mail do destinatário |
| Domínios diferentes, todos com `Unrouteable address` ao mesmo tempo | Não é um problema dos destinatários | Abra um chamado com o **Message ID** e a resposta completa |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
* [Remover endereços que não existem](/ajuda/smtp/erros-de-entrega/endereco-nao-existe/)
# Remover endereços que não existem
> Como reconhecer a recusa de "endereço não existe" em cada provedor, o que muda no seu envio e como evitar que ela se repita.
O servidor de destino respondeu que o endereço não existe — nunca existiu, foi digitado errado ou a conta foi encerrada. É a recusa mais comum, e a única saída é parar de enviar para ele.
## Como reconhecer
[Seção intitulada “Como reconhecer”](#como-reconhecer)
A resposta aparece em **Histórico de Envio → (o e-mail) → Log de Entrega**, com `**` no começo, `after RCPT TO` e o campo **Bounce** em **Hard Bounce**. O texto muda de provedor para provedor:
| Provedor | Resposta típica |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Gmail e Google Workspace | `550-5.1.1 The email account that you tried to reach does not exist` |
| Gmail e Google Workspace (conta desativada) | `550-5.2.1 The email account that you tried to reach is inactive` |
| Outlook.com e Hotmail | `550 5.5.0 Requested action not taken: mailbox unavailable` |
| Microsoft 365 (e-mail de empresas) | `550 5.4.1 Recipient address rejected: Access denied` ou `550 5.1.10 Recipient not found` |
| Yahoo | `554 delivery error: … This user doesn't have a yahoo.com account` |
| Locaweb, KingHost e outras hospedagens | `550 5.1.1 … Recipient address rejected: User unknown in virtual mailbox table` (ou `relay recipient table`) |
| Outros servidores | `User unknown`, `No such user`, `525 5.7.13 Disabled recipient address` |
Microsoft 365 usa `5.4.1` para duas coisas
`Recipient address rejected: Access denied` quer dizer que o endereço não existe na empresa do destinatário. Já `Relay Access Denied`, com o mesmo código, é problema do domínio — veja [Tratar um domínio que não recebe e-mail](/ajuda/smtp/erros-de-entrega/dominio-nao-recebe-email/).
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Confira a grafia do endereço na resposta. Erros de digitação são a causa mais frequente: `gmial.com`, `hotmal.com`, `.com` no lugar de `.com.br`, um ponto ou uma letra a mais.
2. Se foi erro de digitação, corrija o endereço no cadastro do seu sistema (loja, ERP, CRM) — é de lá que ele sai a cada envio.
3. Se a grafia está certa, a conta deixou de existir. Marque o contato como inválido no seu sistema e peça um endereço novo por outro canal, se ele ainda for seu cliente.
4. Para que o problema não volte, valide o endereço no momento do cadastro — veja [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/). Listas antigas ou importadas passam pelo [Validador de E-mail](/ajuda/validador-de-email/validar-uma-lista/) antes do envio.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* O endereço entra sozinho na [lista de supressão](/ajuda/smtp/lista-de-supressao/), com o motivo **Hard Bounce detectado no envio de e-mail**, por 365 dias.
* Enquanto o bloqueio vale, novos envios para ele aparecem no histórico como **Parcialmente descartada** ou **Descartada antes do envio**, com o motivo **Endereço na lista de supressão** — sem nova recusa e sem prejudicar o seu domínio.
* Quando o bloqueio expira, o endereço volta a receber tentativas. Se ele continuar no seu sistema, a recusa se repete e o bloqueio é criado de novo. Por isso o passo 3 é no seu sistema, e não aqui.
* Uma taxa alta de hard bounce derruba a pontuação do domínio. Acompanhe em [Métricas e score](/ajuda/smtp/acompanhar-metricas-e-score/).
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Muitos “não existe” num envio só | Lista antiga, importada ou comprada | Suspenda o envio para essa lista e passe-a pelo [Validador de E-mail](/ajuda/validador-de-email/validar-uma-lista/) |
| O destinatário garante que o endereço existe | A conta foi recriada depois da recusa, ou a empresa dele recusa remetentes externos com a mesma mensagem | Peça que o suporte de e-mail do destinatário confira a conta; depois exclua o bloqueio na [lista de supressão](/ajuda/smtp/lista-de-supressao/) e reenvie |
| O endereço foi corrigido no sistema, mas o cliente segue sem receber | A correção não chegou ao envio, ou o endereço novo tem outro problema | Busque o endereço novo no **Histórico de Envio** e leia a resposta dele |
| A recusa fala em `Relay access denied` | Não é o endereço, é o domínio | Veja [Tratar um domínio que não recebe e-mail](/ajuda/smtp/erros-de-entrega/dominio-nao-recebe-email/) |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
* [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/)
# Lidar com entregas adiadas pelo destino
> O que fazer quando o destino pede para tentar mais tarde — limite de recebimento, reputação, caixa cheia ou servidor fora do ar.
O servidor de destino não recusou a mensagem de vez: pediu para tentar mais tarde, ou não respondeu. A iPORTO tenta de novo sozinha. Na maioria das vezes não há nada a fazer — mas, quando o adiamento se repete num provedor, ele é o aviso de que esse provedor está desconfiando do volume ou da reputação do seu envio.
## Como reconhecer
[Seção intitulada “Como reconhecer”](#como-reconhecer)
Em **Histórico de Envio → (o e-mail) → Log de Entrega**, a resposta começa com `==` ou traz um código que começa com `4`. Enquanto há novas tentativas, a mensagem fica como **Em entrega**.
| Provedor | Resposta típica | O que quer dizer |
| ------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Gmail | `421-4.7.28 Gmail has detected an unusual rate of email …` | Volume acima do normal vindo do seu domínio, do IP ou dos links da mensagem |
| Gmail | `421-4.7.0 Try again later, closing connection` | Limite temporário, muitas vezes ligado à reputação |
| Gmail | `450-4.2.1 The user you are trying to contact is receiving email too quickly` | Aquele destinatário está recebendo e-mails demais agora |
| Gmail | `452-4.2.2 The recipient's inbox is out of storage space` | Caixa cheia |
| Microsoft | `451 4.7.650 The mail server [IP] has been temporarily rate limited due to IP reputation` | Limite por reputação do IP de envio |
| Microsoft 365 | `4.4.7 Message expired` | As tentativas se esgotaram sem que o destino aceitasse |
| Yahoo e AOL | `421 4.7.0 [TSS04] Messages from … temporarily deferred due to unexpected volume or user complaints` | Volume fora do normal ou reclamações de destinatários |
| Qualquer um | `Connection timed out` | O servidor do destino não respondeu |
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Veja se o adiamento é pontual ou se repete. Em **Histórico de Envio**, abra **Filtros Avançados** e marque **Apenas com Soft Bounce**.
2. Abra algumas mensagens e olhe o `H=` da resposta: os adiamentos estão concentrados num provedor só (`google.com`, `outlook.com`, `yahoodns.net`) ou espalhados?
3. Siga o caso:
| O que você encontrou | O que fazer |
| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Caixa cheia, ou `receiving email too quickly`, num destinatário só | Nada. É do destinatário; se continuar por dias, procure-o por outro canal |
| `Connection timed out` sempre no mesmo domínio | O servidor do destinatário está instável. Se durar dias, veja [Tratar um domínio que não recebe e-mail](/ajuda/smtp/erros-de-entrega/dominio-nao-recebe-email/) |
| `4.7.28`, `4.7.650` ou `TSS04` concentrados num provedor | Reduza o volume para esse provedor: espalhe o envio ao longo do dia em vez de disparar tudo de uma vez e priorize quem abriu ou clicou recentemente. Confira se há reclamações em **Alertas de SPAM**, na página do domínio |
| `421-4.7.26`, `4.7.27`, `4.7.30` ou `4.7.32` | É autenticação, ainda em forma de aviso. Veja [Corrigir uma recusa por autenticação](/ajuda/smtp/erros-de-entrega/autenticacao-spf-dkim-dmarc/) antes que vire recusa definitiva |
| Adiamentos em vários provedores ao mesmo tempo | Abra um chamado com o **Message ID** de algumas mensagens e a resposta completa |
Não reenvie o que está “Em entrega”
Enquanto a mensagem está **Em entrega**, as novas tentativas já estão acontecendo. Reenviar pelo seu sistema cria uma segunda cópia: o destinatário recebe duas vezes, e o volume a mais piora o limite que causou o adiamento.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* Se o destino aceitar numa nova tentativa, a mensagem termina como **Processada com sucesso**.
* Se as tentativas se esgotarem, ela termina como **Não entregue**, e o destinatário entra na [lista de supressão](/ajuda/smtp/lista-de-supressao/) com o motivo **Soft Bounce detectado no envio de e-mail**, por 7 dias. Quando a causa foi só `Connection timed out`, o endereço não é bloqueado.
* Limites por reputação melhoram com o tempo quando o volume fica estável e as reclamações caem. Acompanhe em [Métricas e score](/ajuda/smtp/acompanhar-metricas-e-score/).
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| Um provedor adia todo dia no mesmo horário | O envio sai concentrado nesse horário | Espalhe o disparo ao longo do dia |
| Os adiamentos começaram depois de um envio para uma lista nova | Muitos destinatários sem interesse, ou endereços inválidos, numa leva só | Valide a lista com o [Validador de E-mail](/ajuda/validador-de-email/validar-uma-lista/) e retome com volume menor |
| Mensagem parada em **Em entrega** há muito tempo | O destino segue adiando | Leia a resposta mais recente no **Log de Entrega**; se o destino não responde há dias, trate como domínio fora do ar |
| O adiamento virou recusa com `5.7.1` ou `likely unsolicited` | O provedor passou do limite para o bloqueio | Revise o conteúdo e os links e confira a saúde do domínio em [Métricas e score](/ajuda/smtp/acompanhar-metricas-e-score/) |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Acompanhar as métricas e a saúde do domínio](/ajuda/smtp/acompanhar-metricas-e-score/)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
# Corrigir uma recusa pelo formato da mensagem
> Quando o destino recusa porque a mensagem saiu sem remetente, com cabeçalho duplicado ou sem identificador — e como achar o defeito nos cabeçalhos.
O servidor de destino recebeu a mensagem inteira e a recusou porque ela não segue o padrão de e-mail: falta o remetente, um cabeçalho aparece duas vezes, o identificador da mensagem está ausente. Quem monta a mensagem é o seu sistema, então o defeito está lá — e se repete em todo envio dele até ser corrigido.
## Como reconhecer
[Seção intitulada “Como reconhecer”](#como-reconhecer)
Em **Histórico de Envio → (o e-mail) → Log de Entrega**, a resposta vem `after end of data`. O Gmail é o mais rigoroso e diz exatamente o que falta:
| Resposta do Gmail | O que está errado |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `550-5.7.1 … not RFC 5322 compliant: 'From' header is missing` | A mensagem saiu sem a linha `From:` |
| `550-5.7.1 … not RFC 5322 compliant because it has multiple From: headers` | Há duas linhas `From:` |
| `550-5.7.1 … not RFC 5322 compliant because it has duplicate headers` | Outro cabeçalho repetido — `Subject:`, `To:`, `Date:` |
| `550-5.7.1 Messages with multiple addresses in the From: header are not accepted` | O `From:` tem mais de um endereço |
| `550-5.7.1 Messages missing a valid address in the From: header … are not accepted` | O `From:` está vazio ou mal escrito |
| `550-5.7.1 Messages missing a valid Message-ID: header are not accepted` | Falta o identificador da mensagem |
Outros provedores recusam pelos mesmos motivos com textos mais vagos. O Yahoo cita cabeçalho duplicado ou malformado, tipo de conteúdo (MIME) incorreto e data fora do intervalo aceito.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Em **Histórico de Envio**, abra a mensagem recusada e vá na aba **Cabecalhos**. Clique em **Copiar** para trabalhar com o texto.
2. Confira, linha por linha:
* existe **uma** linha `From:`, com **um** endereço, do domínio que você cadastrou;
* nenhum cabeçalho aparece duas vezes;
* existem `Date:` e `Message-ID:`.
3. Corrija no seu sistema. As causas mais comuns:
| Causa | Onde mexer |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| O remetente vem de uma variável que ficou vazia (um cadastro de loja sem e-mail, um modelo sem o campo preenchido) | O modelo ou o cadastro que alimenta o `From` |
| O código define o remetente e um “cabeçalho extra” define de novo | Deixe o remetente só no campo próprio da biblioteca (`setFrom`, `from`, `MAIL_FROM_ADDRESS`) e tire o `From` dos cabeçalhos extras |
| A mensagem é montada à mão, linha por linha | Use uma biblioteca de e-mail, que monta os cabeçalhos no padrão — veja os exemplos em [Conectar o seu sistema](/ajuda/smtp/conectar-seu-sistema/) |
| Nome do remetente com acento ou vírgula, escrito sem aspas | Deixe a biblioteca montar o nome; não escreva a linha `From:` como texto |
4. Envie uma mensagem de teste para um endereço seu no Gmail e confira, no **Histórico de Envio**, se ela saiu como **Processada com sucesso**.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* A correção vale para os próximos envios. As mensagens já recusadas não são reenviadas sozinhas: reenvie pelo seu sistema.
* Os destinatários recusados podem ter entrado na [lista de supressão](/ajuda/smtp/lista-de-supressao/) — por 365 dias se o campo **Bounce** mostrou **Hard Bounce**, por 7 dias se mostrou **Soft Bounce**. O defeito era da mensagem, e não deles: exclua **só** esses bloqueios antes de reenviar. O motivo de cada um traz o ID de Histórico da mensagem que o criou.
Não esvazie a lista de supressão inteira
Exclua só os bloqueios das mensagens recusadas pelo formato. Os outros impedem o reenvio para endereços que realmente não recebem, e um bloqueio excluído não pode ser recuperado.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Só o Gmail recusa; Outlook e outros entregam | O Gmail confere o formato com mais rigor; o defeito está em todas as mensagens | Corrija mesmo assim — os outros provedores tendem a mandar essas mensagens para o spam |
| O seu código define o remetente, e a recusa diz que o `From:` falta | A mensagem é montada à mão, e uma linha em branco antes do `From:` o empurra para o corpo da mensagem | Confira a aba **Cabecalhos**: se o `From:` não aparece lá, use uma biblioteca de e-mail para montar a mensagem |
| Só alguns envios são recusados | Um modelo ou um caminho do seu sistema monta a mensagem diferente dos outros | Compare os cabeçalhos de uma mensagem recusada com os de uma entregue |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Conectar o seu sistema ao SMTP](/ajuda/smtp/conectar-seu-sistema/)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
# IP dedicado — quando resolve, e quando não
> O que muda com um IP só seu, e em que situações ele não é a solução do problema.
Por padrão, os envios saem por **IPs compartilhados**: endereços usados por vários clientes ao mesmo tempo. Um IP dedicado é um endereço usado só pelo seu domínio.
Este artigo existe para separar as duas perguntas que costumam se misturar: *“o IP dedicado melhora a minha entrega?”* e *“o IP dedicado resolve o meu problema de agora?”*. Nem sempre a resposta é a mesma.
## O que muda com um IP dedicado
[Seção intitulada “O que muda com um IP dedicado”](#o-que-muda-com-um-ip-dedicado)
| | |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **A reputação é sua** | No IP compartilhado, o comportamento dos outros clientes afeta a sua entrega — e o seu afeta a deles |
| **Previsibilidade** | Mudanças na sua taxa de entrega passam a ter relação direta com o que você enviou |
| **Volume constante ajuda** | Os provedores reconhecem remetentes regulares; quem envia pouco e esporadicamente aquece o IP mais devagar |
## Quando ele NÃO resolve
[Seção intitulada “Quando ele NÃO resolve”](#quando-ele-não-resolve)
Pontuação baixa não é resolvida por IP dedicado
Se o seu domínio está com a pontuação abaixo do mínimo, o envio é interrompido **antes** de qualquer IP ser escolhido. Trocar o IP não muda isso — a régua da pontuação é aplicada primeiro.
Veja [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/).
| Situação | O IP dedicado resolve? | O que resolve |
| -------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Pontuação abaixo do mínimo | **Não** — o envio para antes do IP | Corrigir a causa da perda: DNS, endereços inválidos, reclamações |
| SPF e DKIM não publicados | **Não** | [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/) |
| Endereços inválidos entrando pelo formulário | **Não** — o bounce continua acontecendo | [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/) |
| Destinatários marcando como spam | **Não** — a reclamação segue o remetente, não o IP | Enviar só para quem pediu, com descadastro visível |
| Entrega instável sem causa no seu envio | **Pode ajudar** | Avaliar com o suporte |
| Volume alto e constante, com lista limpa | **Sim, costuma ajudar** | — |
## A ordem que economiza tempo
[Seção intitulada “A ordem que economiza tempo”](#a-ordem-que-economiza-tempo)
1. **Veja a maior perda.** Na página de pontuação do domínio, o card mostra qual causa está pesando mais e o que a resolve.
2. **Corrija essa causa.** DNS é a mais comum e a mais rápida — publicar dois registros.
3. **Use o botão Verificar agora** e confirme que a pontuação subiu.
4. **Só então avalie o IP dedicado**, se a entrega continuar aquém com a pontuação boa.
Fazer na ordem inversa custa caro: com a causa ainda ativa, o IP novo acumula os mesmos problemas do anterior.
## Como contratar
[Seção intitulada “Como contratar”](#como-contratar)
Fale com o suporte pela [abertura de chamado](/ajuda/atendimento/abrir-um-chamado/). A disponibilidade e as condições dependem do seu plano e do volume de envio.
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/)
* [Acompanhar as métricas e a pontuação do domínio](/ajuda/smtp/acompanhar-metricas-e-score/)
# Impedir envios para um endereço (lista de supressão)
> Bloquear um e-mail, um domínio ou um usuário para que o SMTP não envie mais para eles.
A lista de supressão impede que o SMTP envie para endereços que não devem mais receber: quem pediu para sair, endereços que geram hard bounce, domínios de destino problemáticos.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do SMTP, vá em **Infraestrutura → Lista de Supressão** e clique em **Adicionar**.
2. Em **E-mail**, digite um endereço completo, como `usuario@dominio.com.br` — mesmo que a intenção seja bloquear o domínio inteiro.
3. Em **Tipo de Bloqueio**, escolha o alcance:
* **E-mail** — só aquele endereço;
* **Domínio** — todos os endereços do domínio (`@dominio.com.br`);
* **Usuário** — a parte antes do `@`, em qualquer domínio (`usuario@*`).
4. Em **Motivo**, escreva por que está bloqueando — o campo é obrigatório e fica registrado para você lembrar depois.
5. Em **Data de Expiração**, escolha até quando o bloqueio vale — ou deixe em branco para um bloqueio permanente.
6. Clique em **Adicionar**.
Não esvazie a lista para recuperar a pontuação do domínio
A lista de supressão é o que impede o reenvio para endereços que já deram erro. Apagar os bloqueios faz o contrário do que parece: os mesmos endereços voltam a receber, geram os mesmos erros, e a pontuação do domínio cai de novo.
**Um bloqueio excluído não pode ser recuperado.** Se o objetivo é voltar a entregar, o caminho está em [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/).
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* Envios para o que estiver na lista deixam de ser entregues enquanto o bloqueio valer.
* A lista mostra cada bloqueio com o **Tipo**, a data em que **Expira** (ou **Permanente**) e quando foi criado.
* Para desfazer, exclua o bloqueio na lista.
## Endereços que entram sozinhos
[Seção intitulada “Endereços que entram sozinhos”](#endereços-que-entram-sozinhos)
Quando um destinatário marca a sua mensagem como **spam** e o provedor dele avisa a iPORTO, o endereço entra na lista automaticamente, com o motivo **Alerta de SPAM**, sem data de expiração e só para o domínio que enviou a mensagem. Continuar enviando para quem reclamou derruba a reputação do domínio — por isso o bloqueio é imediato.
A reclamação também aparece em **Alertas de SPAM**, na página do domínio — veja [Acompanhar as métricas e a saúde do domínio](/ajuda/smtp/acompanhar-metricas-e-score/).
Nem todo provedor avisa as reclamações, e nem toda reclamação chega: a lista não substitui o descadastro no seu próprio sistema.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Um cliente diz que parou de receber | O endereço ou o domínio dele está na lista — inclusive por ter marcado uma mensagem como spam | Procure na **Lista de Supressão** e confira o motivo; exclua o bloqueio só se a pessoa pediu para voltar a receber |
| Bloqueei um domínio inteiro sem querer | **Tipo de Bloqueio** ficou em **Domínio** | Exclua e crie de novo com o tipo **E-mail** |
| O endereço continua recebendo | O bloqueio expirou, ou foi criado com o endereço digitado diferente | Confira a **Data de Expiração** e a grafia do endereço |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/)
# Configurar SMTP no Joomla
> Configurar o Joomla para enviar e-mails pelo SMTP da iPORTO nas Configurações Globais — servidor, porta 587, usuário e senha — e testar o envio, com o nome de cada campo em português e em inglês.
Por padrão, o Joomla envia os e-mails do site — cadastro de usuário, recuperação de senha, formulários de contato — pelo método **PHP Mail**, que usa a função de e-mail do servidor da hospedagem. Essa mensagem sai sem autenticar o seu domínio, e Gmail, Outlook e os demais provedores desconfiam dela: ela tende a ir para o spam ou a ser recusada sem que ninguém fique sabendo. Com o método **SMTP**, o Joomla passa a entregar cada e-mail a um servidor que autentica o seu domínio — aqui, o SMTP da iPORTO. Não é preciso instalar extensão: a configuração já vem no Joomla.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Uma conta no SMTP da iPORTO. Se ainda não tem, veja os [planos do SMTP](https://www.iporto.com.br/pricing/smtp) — dá para testar por 7 dias, sem cartão.
* Um domínio cadastrado, com os registros DNS publicados — veja [Adicionar um domínio de envio](/ajuda/smtp/adicionar-um-dominio/) e [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/).
* Uma credencial SMTP para o site, como `site@suaempresa.com.br` — veja [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/).
* Acesso de **Super Usuário** ao painel do Joomla — só ele abre as Configurações Globais.
* A hospedagem do site precisa permitir conexões de saída na porta **587** — ou, se ela estiver bloqueada, na **465**. O teste do passo 3 mostra se há bloqueio.
A tela pode aparecer em inglês
No Joomla 6 com o pacote de idioma português do Brasil atual, a tela **Configurações Globais** aparece em inglês mesmo com o restante do painel em português. Por isso, este guia dá os dois nomes de cada campo.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
### 1. Abrir a configuração de e-mail
[Seção intitulada “1. Abrir a configuração de e-mail”](#1-abrir-a-configuração-de-e-mail)
1. Entre no painel de administração do Joomla — o endereço do site seguido de `/administrator`.
2. Vá em **Sistema → Configurar → Configurações Globais**.
3. Abra a aba **Servidor** (*Server*) e desça até o bloco **E-mail** (*Mail*).
### 2. Preencher os dados da iPORTO
[Seção intitulada “2. Preencher os dados da iPORTO”](#2-preencher-os-dados-da-iporto)
| Campo | Em inglês | O que preencher | Onde achar |
| ------------------------ | --------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Enviar email** | *Send Mail* | **Sim** (já vem assim) | — |
| **Método** | *Mailer* | **SMTP** | — |
| **Email do Remetente** | *From Email* | Um endereço do seu domínio, como `site@suaempresa.com.br` | O domínio cadastrado no painel do SMTP |
| **Nome do Remetente** | *From Name* | O nome que o destinatário vai ver, como `Sua Empresa` | — |
| **Autenticação SMTP** | *SMTP Authentication* | **Username and Password** | — |
| **Segurança SMTP** | *SMTP Security* | **STARTTLS** | — |
| **Porta** | *SMTP Port* | `587` | — |
| **Nome de Usuário SMTP** | *SMTP Username* | A credencial completa, como `site@suaempresa.com.br` | Painel do SMTP: **Infraestrutura → Domínios (SMTP)** → o domínio → aba **Credenciais** |
| **Senha** | *SMTP Password* | A senha da credencial | No card da credencial, em **Senha**, pelo botão de copiar |
| **Servidor SMTP** | *SMTP Host* | `smtp-avancado.com` | — |
Os campos que não aparecem na tabela ficam como estão. Clique em **Salvar**, no alto da tela.
Depois de salvar, o campo **Senha** volta vazio e travado. É proteção do Joomla: a senha continua guardada. Para trocá-la, clique em **Modificar**, ao lado do campo.
### 3. Testar o envio
[Seção intitulada “3. Testar o envio”](#3-testar-o-envio)
1. Ainda no bloco **E-mail**, clique em **Enviar email de teste** (*Send Test Mail*).
2. O Joomla envia o teste para o e-mail do **seu usuário** — o que você usa para entrar no painel —, e não para o remetente.
3. Se deu certo, a tela mostra *The email was sent to … using SMTP.* Abra o painel do SMTP e confira o envio em [Histórico de envio](/ajuda/smtp/consultar-o-historico-de-envio/).
Salve antes de testar
O botão testa o que está na tela, mesmo sem salvar. Antes de salvar, a resposta é *The email was sent to … but using SMTP as fallback* — um aviso confuso, que só quer dizer que a configuração salva ainda é outra. Salve e teste de novo.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
Cada e-mail do site que o servidor aceitar entra no **Histórico de Envio** do painel do SMTP, com o status da entrega. Aceito pelo servidor não quer dizer entregue na caixa de entrada: o destino ainda pode recusar, adiar ou filtrar a mensagem — e é o histórico que mostra o que aconteceu.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SMTP Error: Could not authenticate.` | Usuário ou senha errados, ou o usuário foi informado sem o `@domínio` | Use a credencial completa como usuário. Para digitar a senha de novo, clique em **Modificar** ao lado do campo e cole a senha copiada do painel. Confira também se o **Status** da credencial está ativo |
| `SMTP Error: Could not connect to SMTP host.` logo depois do clique | **Segurança SMTP** está em **SSL/TLS** com a porta 587 — SSL/TLS só funciona na 465 | Use **STARTTLS** com a porta `587`, ou **SSL/TLS** com a `465` |
| `SMTP Error: Could not connect to SMTP host.` depois de uma espera longa, de minutos | A hospedagem bloqueia a saída na porta 587 | Use a alternativa: **Segurança SMTP** em **SSL/TLS** e **Porta** `465`. Se também falhar, peça ao suporte da hospedagem para liberar conexões de saída na 587 ou na 465 para `smtp-avancado.com`. Algumas hospedagens só permitem o servidor de e-mail delas — nesse caso, não há configuração no Joomla que resolva |
| `SMTP Error: The following recipients failed`, com um motivo como `Rejected because … is in a black list` | **Autenticação SMTP** está em **Desativado**. Sem usuário e senha, o servidor trata o site como um desconhecido e aplica a ele as listas de bloqueio de IP — por isso o erro fala em lista, e não em senha | Escolha **Username and Password** e preencha usuário e senha |
| O teste diz que o e-mail foi enviado *using PHP Mail*, e ele não aparece no histórico | **Método** ainda está em **PHP Mail**, ou faltou usuário ou senha e o Joomla voltou para o envio da hospedagem | Escolha **SMTP** em **Método**, confira usuário e senha, salve e teste de novo |
| O e-mail aparece no histórico como recusado ou devolvido | O destino recusou a mensagem depois de o servidor aceitá-la | Veja [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/) |
# Configurar SMTP no Mautic
> Configurar o Mautic para enviar campanhas e e-mails de segmento pelo SMTP da iPORTO — a DSN de e-mail com servidor, porta 587, usuário e senha —, com um domínio de marketing, e testar o envio.
O Mautic monta campanhas, segmentos e automações, mas não entrega e-mail sozinho: ele precisa de um servidor de envio. Configurado com o SMTP da iPORTO, cada e-mail do Mautic sai por um servidor que autentica o seu domínio, e o envio aparece no histórico do painel do SMTP, com o status da entrega.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Uma conta no SMTP da iPORTO. Se ainda não tem, veja os [planos do SMTP](https://www.iporto.com.br/pricing/smtp) — dá para testar por 7 dias, sem cartão.
* **Um domínio cadastrado com Tipo de envio → Marketing.** O Mautic envia campanha, e campanha é marketing: o SMTP só aceita envio de marketing em domínio criado como **Marketing**. O tipo é escolhido na hora de cadastrar o domínio — veja [Adicionar um domínio de envio](/ajuda/smtp/adicionar-um-dominio/).
* Os registros DNS desse domínio publicados — veja [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/).
* Uma credencial SMTP nesse domínio, como `contato@news.suaempresa.com.br` — veja [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/).
* Acesso de administrador ao Mautic.
* O servidor do Mautic precisa permitir conexões de saída na porta **587** — ou, se ela estiver bloqueada, na **465**.
Seu domínio principal já está como Transacional?
Não use esse domínio no Mautic. Num domínio cadastrado como **Transacional**, não se envia nada com cunho de marketing. Para manter o seu domínio, cadastre um **subdomínio** só para o marketing — como `news.suaempresa.com.br` — com **Tipo de envio → Marketing**, e use-o no Mautic.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
### 1. Abrir a configuração de e-mail
[Seção intitulada “1. Abrir a configuração de e-mail”](#1-abrir-a-configuração-de-e-mail)
1. No Mautic, clique na engrenagem (**Configurações**), no alto da tela, e depois em **Configuração**.
2. Abra a aba **Configurações de email**.
### 2. Preencher os dados da iPORTO
[Seção intitulada “2. Preencher os dados da iPORTO”](#2-preencher-os-dados-da-iporto)
| Campo | O que preencher | Onde achar |
| ---------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Nome utilizado ao enviar este e-mail** | O nome que o destinatário vai ver, como `Sua Empresa` | — |
| **Enviar email a partir do endereço** | Um endereço do domínio de marketing, como `contato@news.suaempresa.com.br` | O domínio cadastrado no painel do SMTP |
| **Remetente é dono** | **Não** | — |
| **Esquema** (em **DSN de E-mail**) | `smtp` | — |
| **Host** | `smtp-avancado.com` | — |
| **Porta** | `587` | — |
| **Caminho** | Vazio | — |
| **Usuário** | A credencial completa, como `contato@news.suaempresa.com.br` | Painel do SMTP: **Infraestrutura → Domínios (SMTP)** → o domínio → aba **Credenciais** |
| **Senha** | A senha da credencial | No card da credencial, em **Senha**, pelo botão de copiar |
Os demais campos ficam como estão — inclusive **Endereço de caminho de retorno personalizado (bounce)**, vazio, e **Disable unsubscribe link in header**, em **Não**. Clique em **Salvar**.
* **Digite o usuário com o `@` normalmente.** O Mautic converte para o formato da DSN ao salvar. Só quem edita a DSN direto no arquivo de configuração do Mautic precisa escrever o `@` como `%40`.
* **Por que “Remetente é dono” em Não.** Com **Sim**, cada e-mail sai em nome do usuário do Mautic dono do contato — e o endereço desse usuário pode não ser do seu domínio de marketing. A mensagem chegaria ao destino em nome de um domínio que você não autenticou. É o valor padrão para os e-mails que você criar daqui em diante.
### 3. Testar o envio
[Seção intitulada “3. Testar o envio”](#3-testar-o-envio)
1. Depois de salvar, ainda na aba **Configurações de email**, clique em **Enviar email de teste**, no bloco **DSN de E-mail**.
2. O Mautic envia o teste para o e-mail do **seu usuário** — o que você usa para entrar no Mautic.
3. Se deu certo, aparece **Sucesso!**. Abra o painel do SMTP e confira o envio em [Histórico de envio](/ajuda/smtp/consultar-o-historico-de-envio/).
O botão de teste fica desativado
Ao mudar qualquer campo da DSN, o botão se desativa e aparece **Salve alterações para testar o DSN.** O teste usa sempre a configuração salva: salve e o botão volta.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* **Os e-mails de segmento saem pelas tarefas agendadas do Mautic** (o cron do servidor dele), e não na hora em que você publica. Com elas rodando, cada envio aceito pelo servidor entra no **Histórico de Envio** do painel do SMTP, com o status da entrega.
* **Descadastro em um clique.** Nos e-mails com link de descadastro, o Mautic já inclui os cabeçalhos que fazem Gmail e Yahoo mostrarem o botão **Cancelar inscrição** — veja [Ativar o descadastro em um clique](/ajuda/smtp/ativar-o-descadastro-em-um-clique/). Para isso, **Disable unsubscribe link in header** precisa ficar em **Não**.
* **Devoluções (bounces).** O Mautic não fica sabendo sozinho dos e-mails que voltaram: elas ficam no histórico do painel do SMTP, e o próprio SMTP passa a bloquear novos envios para os endereços que devolveram — veja [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/).
Aceito pelo servidor não quer dizer entregue na caixa de entrada: o destino ainda pode recusar, adiar ou filtrar a mensagem — e é o histórico que mostra o que aconteceu.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Failed to authenticate on SMTP server with username "…"`, com `535 Incorrect authentication data` | Usuário ou senha errados, ou o usuário foi informado sem o `@domínio` | Use a credencial completa como usuário e copie a senha de novo pelo botão do painel. Confira também se o **Status** da credencial está ativo |
| `Connection could not be established with host "ssl://smtp-avancado.com:587"`, com `wrong version number` | **Esquema** está como `smtps`, que não funciona na porta 587 | Use `smtp`. Com `smtp`, o Mautic escolhe a criptografia certa sozinho: STARTTLS na 587 e SSL na 465 |
| `Connection could not be established with host "smtp-avancado.com:587"`, com `Connection timed out`, depois de cerca de um minuto | O servidor do Mautic não consegue sair pela porta 587 | Troque a **Porta** para `465`, mantendo o **Esquema** `smtp`. Se também falhar, peça ao provedor do servidor para liberar conexões de saída na 587 ou na 465 para `smtp-avancado.com` |
| O botão **Enviar email de teste** está desativado | Algum campo da DSN mudou e ainda não foi salvo | Clique em **Salvar** e teste de novo |
| O teste funciona, mas o e-mail de segmento não sai | As tarefas agendadas (cron) do Mautic não estão rodando | Confira com quem administra o servidor do Mautic se o cron está configurado |
| O e-mail sai com um remetente diferente do configurado | **Remetente é dono** está em **Sim** | Mude para **Não** |
| O e-mail aparece no histórico como recusado ou devolvido | O destino recusou a mensagem depois de o servidor aceitá-la | Veja [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/) |
# Configurar SMTP no Supabase
> Configurar o Supabase Auth para enviar os e-mails de login — confirmação de cadastro, recuperação de senha, link mágico, convite — pelo SMTP da iPORTO, ajustar o limite de envio por hora e testar com um convite. Vale também para apps do Lovable com Supabase próprio.
O Supabase Auth envia os e-mails de login do seu app — confirmação de cadastro, recuperação de senha, link mágico, convite —, mas o servidor de e-mail que vem com ele é só para testes: envia poucas mensagens por hora e só para os membros da equipe do projeto. Para o app funcionar com usuários de verdade, o Supabase pede um servidor SMTP próprio — aqui, o SMTP da iPORTO. A configuração está disponível em todos os planos do Supabase, inclusive no gratuito.
Usa Lovable?
Este guia vale para projetos do Lovable ligados a um **Supabase próprio**. No **Lovable Cloud** (o backend que já vem no Lovable), os e-mails de login saem pelo próprio Lovable, e não há onde configurar SMTP. Para os e-mails que o seu app envia — pedido, formulário, aviso —, veja o [guia de Lovable na seção de API](/api/guias/lovable/).
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Uma conta no SMTP da iPORTO. Se ainda não tem, veja os [planos do SMTP](https://www.iporto.com.br/pricing/smtp) — dá para testar por 7 dias, sem cartão.
* Um domínio cadastrado como **Transacional** — e-mail de login é transacional —, com os registros DNS publicados. Veja [Adicionar um domínio de envio](/ajuda/smtp/adicionar-um-dominio/) e [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/).
* Uma credencial SMTP nesse domínio, como `login@suaempresa.com.br` — veja [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/).
* Acesso de administrador ao projeto no painel do Supabase.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
### 1. Ligar o SMTP próprio
[Seção intitulada “1. Ligar o SMTP próprio”](#1-ligar-o-smtp-próprio)
1. No painel do Supabase, abra o projeto e vá em **Authentication**. No menu lateral, no grupo **Notifications**, clique em **Emails** e abra a aba **SMTP Settings**.
2. Ligue **Enable custom SMTP** e preencha:
| Campo | O que preencher | Onde achar |
| ------------------------ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Sender email address** | Um endereço do seu domínio, como `login@suaempresa.com.br` | O domínio cadastrado no painel do SMTP |
| **Sender name** | O nome que o usuário vai ver, como `Sua Empresa` | — |
| **Host** | `smtp-avancado.com` | — |
| **Port number** | `587` | — |
| **Username** | A credencial completa, como `login@suaempresa.com.br` | Painel do SMTP: **Infraestrutura → Domínios (SMTP)** → o domínio → aba **Credenciais** |
| **Password** | A senha da credencial | No card da credencial, em **Senha**, pelo botão de copiar |
3. Clique em **Save changes**.
Depois de salvar, o Supabase não mostra mais a senha: o campo fica com pontos e o aviso *Stored password is hidden*. Ela continua guardada. Para trocá-la, digite a nova por cima e salve.
### 2. Ajustar o limite de envio
[Seção intitulada “2. Ajustar o limite de envio”](#2-ajustar-o-limite-de-envio)
Com o SMTP próprio ligado, o Supabase limita os e-mails de login a **30 por hora** no projeto inteiro. Para um app com usuários de verdade, isso costuma ser pouco:
1. Vá em **Authentication → Rate Limits**.
2. Aumente **Rate limit for sending emails** (em *emails/h*) para o volume que o seu app precisa — sem passar do que o seu plano no SMTP da iPORTO comporta.
3. Clique em **Save changes**.
Na mesma tela, **Minimum interval per user** é o tempo mínimo entre dois e-mails para o mesmo usuário — 60 segundos, por padrão. Ele evita que um usuário receba vários e-mails seguidos ao clicar mais de uma vez em “reenviar”; deixe como está.
### 3. Testar o envio
[Seção intitulada “3. Testar o envio”](#3-testar-o-envio)
1. Vá em **Authentication → Users** e clique em **Add user → Send invitation**.
2. Na janela **Invite a new user**, digite uma caixa de e-mail sua em **User email** e clique em **Invite user**.
3. O convite chega com o assunto *You’ve been invited*. Abra o painel do SMTP e confira o envio em [Histórico de envio](/ajuda/smtp/consultar-o-historico-de-envio/).
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
Todo e-mail de login do projeto passa a sair pelo SMTP da iPORTO e entra no **Histórico de Envio** do painel do SMTP, com o status da entrega. Os textos dos e-mails continuam sendo editados no Supabase, em **Authentication → Emails**, na aba **Templates**.
**Confira para onde os links dos e-mails levam.** O link de cada e-mail de login — **Accept invitation**, confirmação de cadastro, troca de senha — volta para o endereço do seu app definido em **Authentication → URL Configuration**, no campo **Site URL**. Num projeto novo, ele vem como `http://localhost:3000`, que só funciona no computador de quem desenvolve. Troque pelo endereço público do app e clique em **Save changes**.
Aceito pelo servidor não quer dizer entregue na caixa de entrada: o destino ainda pode recusar, adiar ou filtrar a mensagem — e é o histórico que mostra o que aconteceu.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Failed to invite user` … `Error sending invite email`, e nada aparece no histórico | A tela não diz o motivo. Em **Logs → Explorer**, na fonte `auth_logs`, o erro `535 "Incorrect authentication data"` quer dizer usuário ou senha errados | Use a credencial completa como **Username**. Copie a senha de novo pelo botão do painel, cole por cima dos pontos em **Password** e salve. Confira também se o **Status** da credencial está ativo |
| Os primeiros e-mails saem, e depois o Supabase recusa novos envios por limite | O limite de envio do projeto foi atingido | Aumente **Rate limit for sending emails** em **Authentication → Rate Limits** |
| Um segundo e-mail para o mesmo usuário, logo depois do primeiro, não sai | **Minimum interval per user** — por padrão, 60 segundos entre dois e-mails para o mesmo usuário | Espere o intervalo e tente de novo |
| O e-mail chega, mas o link abre `localhost:3000` ou uma página que não carrega | O **Site URL** do projeto ainda é o padrão | Em **Authentication → URL Configuration**, troque o **Site URL** pelo endereço público do app |
| O e-mail sai com o remetente do Supabase, e não aparece no histórico | **Enable custom SMTP** está desligado, ou a configuração não foi salva | Ligue, confira os campos e clique em **Save changes** |
| O e-mail aparece no histórico como recusado ou devolvido | O destino recusou a mensagem depois de o servidor aceitá-la | Veja [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/) |
# Configurar SMTP no WordPress
> Configurar o WordPress para enviar e-mails pelo SMTP da iPORTO com o plugin WP Mail SMTP — servidor, porta 587, usuário e senha —, testar o envio e ajustar o WooCommerce.
Por padrão, o WordPress envia os e-mails do site — formulário de contato, recuperação de senha, pedidos do WooCommerce — pela função de e-mail do servidor da hospedagem. Essa mensagem sai sem autenticar o seu domínio, e Gmail, Outlook e os demais provedores desconfiam dela: ela tende a ir para o spam ou a ser recusada sem que ninguém fique sabendo. Com um plugin de SMTP, o WordPress passa a entregar cada e-mail a um servidor que autentica o seu domínio — aqui, o SMTP da iPORTO.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Uma conta no SMTP da iPORTO. Se ainda não tem, veja os [planos do SMTP](https://www.iporto.com.br/pricing/smtp) — dá para testar por 7 dias, sem cartão.
* Um domínio cadastrado, com os registros DNS publicados — veja [Adicionar um domínio de envio](/ajuda/smtp/adicionar-um-dominio/) e [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/).
* Uma credencial SMTP para o site, como `site@suaempresa.com.br` — veja [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/). Uma credencial só para o site deixa claro, no histórico, quais envios vieram dele.
* Acesso de administrador ao WordPress.
* A hospedagem do site precisa permitir conexões de saída na porta **587** — ou, se ela estiver bloqueada, na **465**. A maioria permite; se a sua não permitir, o teste do passo 3 mostra (veja [Se der errado](#se-der-errado)).
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
### 1. Instalar o WP Mail SMTP
[Seção intitulada “1. Instalar o WP Mail SMTP”](#1-instalar-o-wp-mail-smtp)
1. No WordPress, vá em **Plugins → Adicionar plugin** e busque por `WP Mail SMTP`.
2. No card **WP Mail SMTP by WPForms**, clique em **Instalar agora** e depois em **Ativar**.
3. O plugin abre o **Assistente de configuração**. Este guia usa a tela de configurações, que é onde você volta quando precisar mudar algo: clique em **Feche e saia do Assistente de configuração**, no rodapé.
### 2. Preencher os dados da iPORTO
[Seção intitulada “2. Preencher os dados da iPORTO”](#2-preencher-os-dados-da-iporto)
Vá em **WP Mail SMTP → Configurações**, na aba **Geral**, e preencha:
| Campo no WP Mail SMTP | O que preencher | Onde achar |
| ------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **E-mail do remetente** | Um endereço do seu domínio, como `site@suaempresa.com.br` | O domínio cadastrado no painel do SMTP |
| **Forçar e-mail do remetente** | Marcado | — |
| **Remetente** | O nome que o destinatário vai ver, como `Sua Empresa` | — |
| **Forçar nome do remetente** | Marcado, se quiser o mesmo nome em todos os e-mails do site | — |
| **Mailer** | **Outro SMTP** | — |
| **Servidor de SMTP** | `smtp-avancado.com` | — |
| **Criptografia** | **TLS** | — |
| **Porta SMTP** | `587` — o plugin preenche sozinho ao escolher **TLS** | — |
| **TLS automático** | Ativado (já vem assim) | — |
| **Autenticação** | Ativado | — |
| **Nome de usuário SMTP** | A credencial completa, como `site@suaempresa.com.br` | Painel do SMTP: **Infraestrutura → Domínios (SMTP)** → o domínio → aba **Credenciais** |
| **Senha SMTP** | A senha da credencial | No card da credencial, em **Senha**, pelo botão de copiar |
Os campos que não aparecem na tabela ficam como estão. Clique em **Salvar configurações**.
**Por que forçar o remetente.** Plugins de formulário e o próprio WooCommerce costumam definir o remetente por conta própria — às vezes com o e-mail de quem preencheu o formulário, de um domínio que não é o seu. O servidor da iPORTO aceita esse envio, mas a mensagem chega ao destino em nome de um domínio que você não autenticou — e o destino pode mandá-la para o spam ou recusá-la. Marcado, **Forçar e-mail do remetente** faz todo e-mail do site sair do endereço do seu domínio. Para continuar respondendo direto a quem preencheu o formulário, use o campo de resposta (Reply-To) do plugin de formulário, e não o remetente.
Senha fora do banco de dados
O WP Mail SMTP guarda a senha criptografada no banco, mas aceita que ela fique no `wp-config.php`, fora do alcance de quem acessa só o banco. Adicione, antes da linha que começa com `/* That's all, stop editing!`:
```php
define( 'WPMS_ON', true );
define( 'WPMS_SMTP_PASS', 'a senha da credencial' );
```
O campo **Senha SMTP** passa a aparecer desativado na tela, com o aviso de que o valor foi definido pela constante `WPMS_SMTP_PASS`. Para trocar a senha depois, troque no arquivo.
### 3. Testar o envio
[Seção intitulada “3. Testar o envio”](#3-testar-o-envio)
1. Vá em **WP Mail SMTP → Ferramentas**, na aba **E-mail de teste**.
2. Em **Enviar para**, digite uma caixa de e-mail sua e clique em **Enviar e-mail**.
3. Se deu certo, o plugin mostra **Test email sent successfully!** — a mensagem vem em inglês mesmo com o WordPress em português. Abra o painel do SMTP e confira o envio em [Histórico de envio](/ajuda/smtp/consultar-o-historico-de-envio/). Se deu errado, o plugin mostra o erro e um registro técnico; veja [Se der errado](#se-der-errado).
## WooCommerce
[Seção intitulada “WooCommerce”](#woocommerce)
O WooCommerce envia os e-mails da loja — pedido recebido, pedido concluído, nova conta — pelo próprio WordPress. Com o WP Mail SMTP configurado, eles já saem pela iPORTO.
Para o remetente da loja não divergir do configurado no plugin, vá em **WooCommerce → Configurações → E-mails** e, em **Opções do e-mail do remetente**, preencha **Nome “De”** e **Endereço de e-mail do remetente** com o mesmo nome e o mesmo endereço do passo 2. Com **Forçar e-mail do remetente** marcado, vale o do WP Mail SMTP de qualquer forma; deixar os dois iguais evita a dúvida de qual está valendo.
## Outros plugins de SMTP
[Seção intitulada “Outros plugins de SMTP”](#outros-plugins-de-smtp)
FluentSMTP, Post SMTP e os demais plugins de SMTP pedem os mesmos dados: servidor `smtp-avancado.com`, porta `587` com criptografia TLS (STARTTLS) — ou `465` com SSL —, autenticação ligada, usuário e senha da credencial. Deixe **um** plugin de SMTP ativo por vez: dois ao mesmo tempo disputam o envio, e o que vale é o que o WordPress carregar por último.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
Cada e-mail do site que o servidor aceitar entra no **Histórico de Envio** do painel do SMTP, com o status da entrega. Aceito pelo servidor não quer dizer entregue na caixa de entrada: o destino ainda pode recusar, adiar ou filtrar a mensagem — e é o histórico que mostra o que aconteceu.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
O teste do passo 3 mostra o erro em inglês, seguido de um registro técnico da conversa com o servidor. A primeira linha do erro e um trecho do registro bastam para achar o caso na tabela.
| Sintoma | Causa provável | O que fazer |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SMTP Error: Could not authenticate.`, e no registro `535 Incorrect authentication data` | Usuário ou senha errados, ou o usuário foi informado sem o `@domínio` | Use a credencial completa como usuário e copie a senha de novo pelo botão do painel. Confira também se o **Status** da credencial está ativo |
| `SMTP Error: Could not connect to SMTP host.`, e no registro `Connection timed out` | A hospedagem bloqueia a saída na porta 587 | Use a alternativa: **Criptografia** em **SSL** e **Porta SMTP** `465` — o plugin troca a porta sozinho ao escolher **SSL**. Se também esgotar o tempo, peça ao suporte da hospedagem para liberar conexões de saída na 587 ou na 465 para `smtp-avancado.com`. Algumas hospedagens só permitem o servidor de e-mail delas — nesse caso, não há configuração no WordPress que resolva |
| `SMTP Error: Could not connect to SMTP host.`, e no registro `wrong version number` | **Criptografia** está em **SSL** com a porta 587 — SSL só funciona na 465 | Use **TLS** com a porta `587`, ou **SSL** com a `465` |
| `SMTP Error: The following recipients failed`, com um motivo como `Rejected because … is in a black list` | **Autenticação** está desativada. Sem usuário e senha, o servidor trata o site como um desconhecido e aplica a ele as listas de bloqueio de IP — por isso o erro fala em lista, e não em senha | Ative **Autenticação** e preencha **Nome de usuário SMTP** e **Senha SMTP**. Com a autenticação ligada, esse bloqueio não se aplica |
| O teste funciona, mas um formulário ou a loja não envia, e o envio não aparece no histórico | Outro plugin de SMTP ativo, ou um plugin de formulário com servidor de envio próprio | Deixe só o WP Mail SMTP ativo; nas configurações do formulário, use o envio padrão do WordPress |
| O e-mail aparece no histórico como recusado ou devolvido | O destino recusou a mensagem depois de o servidor aceitá-la | Veja [Entender por que um e-mail não foi entregue](/ajuda/smtp/entender-falhas-de-entrega/) |
# Publicar os registros DNS do domínio
> Quais registros SPF, DKIM, DMARC e de rastreamento publicar, onde copiá-los e como conferir.
Os registros de DNS provam aos provedores de e-mail que a iPORTO pode enviar em nome do seu domínio. Sem eles, seus e-mails chegam como suspeitos — vão para o spam ou são recusados.
Sem SPF e DKIM, o envio não acontece
A publicação destes registros não é recomendação: sem **SPF** e **DKIM**, a pontuação do domínio fica perto de 12, e abaixo de 45 **nenhuma mensagem é enviada** — mesmo que você nunca tenha tido um problema de entrega.
Depois de publicar, clique em **Verificar agora** na página do domínio: a pontuação é recalculada em segundos. Veja [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/).
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* O domínio precisa estar cadastrado no SMTP — veja [Adicionar um domínio de envio](/ajuda/smtp/adicionar-um-dominio/).
* Tenha à mão o acesso ao painel de DNS do domínio (registro.br, Cloudflare, sua hospedagem…).
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do SMTP, vá em **Infraestrutura → Domínios (SMTP)** e abra o domínio.
2. Na aba **DNS**, o bloco **Configuração para DNS** mostra os registros a publicar. Cada um tem **Tipo**, **Nome**, **TTL** e **Valor**, com um botão para copiar.
3. No painel de DNS do seu domínio, crie cada registro copiando os valores da tela:
| Registro | Tipo | Nome | Para que serve |
| ---------------- | ----- | ----------------- | ------------------------------------------------------------------------- |
| **SPF** | TXT | o próprio domínio | Autoriza os servidores da iPORTO a enviar pelo seu domínio |
| **DKIM** | TXT | `mail._domainkey` | Assina cada e-mail, provando que ele não foi alterado no caminho |
| **DMARC** | TXT | `_dmarc` | Diz aos provedores o que fazer com e-mails que falharem no SPF ou no DKIM |
| **Rastreamento** | CNAME | `track-s1` | Permite medir aberturas e cliques com o seu domínio nos links |
4. Volte à aba **DNS** e clique em **Verificar DNS**.
Um SPF só por domínio
O domínio só pode ter **um** registro TXT começando com `v=spf1`. Se já existe um — porque você usa o Google Workspace ou o Microsoft 365, por exemplo —, **não crie outro**: acrescente o `include` da iPORTO ao registro existente. Exemplo de um SPF unificado:
```plaintext
v=spf1 include:spf.smtp-avancado.com include:_spf.google.com ~all
```
Use o `include` exato que aparece no seu painel.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* O bloco **Registros DNS**, logo abaixo, mostra o que foi encontrado de fato no DNS do seu domínio. SPF, DKIM e DMARC aparecem como **Verificado** ou **Não verificado**.
* O registro de rastreamento aparece como **publicado** ou **aguardando publicação**.
* Mudanças de DNS podem levar algumas horas para se propagar — em casos raros, até 48 horas. Se a verificação ainda não encontrar o registro, espere e clique em **Verificar DNS** de novo.
* O bloco **Registros DNS** também mostra, só para informação, o MX, o site (registro A) e os nameservers do domínio. Eles não são publicados por você aqui.
Sobre o DMARC
O valor sugerido começa com `p=none`: os provedores só relatam, sem bloquear nada. Depois que seus envios estiverem estáveis, você pode endurecer a política para `quarantine` ou `reject`.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| SPF **Não verificado** depois de publicado | Ainda está propagando, ou há dois registros SPF no domínio | Espere algumas horas; confira se existe só um TXT com `v=spf1` |
| SPF verificado, mas os e-mails falham no SPF | O SPF existente não tem o `include` da iPORTO | Acrescente o `include` mostrado no painel ao registro que já existe |
| DKIM **Não verificado** | O nome foi criado errado — alguns painéis de DNS acrescentam o domínio sozinhos e o nome vira `mail._domainkey.suaempresa.com.br.suaempresa.com.br` | Cadastre o nome só como `mail._domainkey` |
| DKIM cortado ou inválido | O valor é longo e foi colado pela metade | Copie de novo com o botão da tela e cole o valor inteiro |
| Rastreamento **aguardando publicação** | O CNAME não foi criado, ou está com proxy ligado | Crie o CNAME `track-s1`; na Cloudflare, deixe o proxy desligado (nuvem cinza) |
| Mudança não aparece há muitas horas | TTL alto no registro antigo | Durante a configuração, use TTL baixo (300 ou 3600) |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/)
* [Acompanhar as métricas e a saúde do domínio](/ajuda/smtp/acompanhar-metricas-e-score/)
# Resetar o cálculo da pontuação
> Fazer os erros antigos deixarem de contar, depois de corrigir a origem dos endereços.
A pontuação olha os **últimos 7 dias**. Isso significa que, mesmo depois de você corrigir o que causava os erros, eles continuam pesando até saírem dessa janela.
O reset do cálculo encurta essa espera: os erros registrados até agora deixam de contar, e a contagem recomeça a partir de hoje.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
| | |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Publique SPF e DKIM** | Sem eles, é o DNS que derruba a pontuação — e o reset não alcança essa perda. O botão recusa enquanto faltarem |
| **Corrija a origem dos endereços** | Se os endereços inválidos continuarem entrando, a pontuação cai de novo na verificação seguinte |
| **Disponível a cada 30 dias** | Por domínio |
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do SMTP, abra **Infraestrutura → Domínios (SMTP)** e clique no domínio.
2. Clique em **Histórico de pontuação**.
3. Na coluna da direita, em **Controles**, clique em **Resetar cálculo de Pontuação do Domínio**.
4. Confirme.
A pontuação é recalculada na hora — você não precisa esperar a próxima verificação.
## O que o reset faz, e o que não faz
[Seção intitulada “O que o reset faz, e o que não faz”](#o-que-o-reset-faz-e-o-que-não-faz)
| Faz | Não faz |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Os erros de endereço registrados até agora deixam de contar na pontuação | Não apaga o histórico de envios |
| A contagem de bounces recomeça a partir de hoje | **Não remove nada da lista de supressão** |
| O envio volta assim que a pontuação passa do mínimo | Não devolve créditos |
| | Não perdoa armadilhas de spam nem reclamações — essas contam por 30 dias, em conta própria |
A lista de supressão continua valendo — e é isso que protege você
Os endereços que deram erro seguem bloqueados depois do reset. É exatamente isso que impede o problema de voltar: sem o bloqueio, o próximo envio para os mesmos endereços geraria os mesmos erros, e a pontuação cairia de novo.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| “Publique os registros SPF e DKIM antes de resetar o cálculo.” | O DNS do domínio está incompleto, e é ele que derruba a pontuação | Veja [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/); depois clique em **Verificar agora** |
| “O próximo reset fica disponível em…” | O reset já foi usado nos últimos 30 dias | Aguarde a data informada. Se corrigiu e o envio não pode esperar, abra um chamado descrevendo a correção |
| A pontuação subiu, mas voltou a cair em seguida | Os endereços inválidos continuam entrando | Veja [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/) |
| A pontuação não mudou depois do reset | A perda não era de bounce | Veja a **Maior perda** no card de pontuação: se for DNS, trap ou spam, o reset não a alcança |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/)
* [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/)
# Validar o e-mail no seu formulário
> Como impedir que endereços digitados errado entrem na sua lista e derrubem a pontuação do domínio.
Se o seu site tem um formulário público — cadastro, orçamento, download — parte dos endereços digitados ali vai estar errada: letra trocada, domínio incompleto, provedor que não existe. Cada um desses é um hard bounce quando você envia, e hard bounce é a causa mais comum de queda na [pontuação do domínio](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/).
Validar o endereço **antes** de aceitar o cadastro é mais barato do que limpar a lista depois.
## O que fazer, em ordem de custo
[Seção intitulada “O que fazer, em ordem de custo”](#o-que-fazer-em-ordem-de-custo)
### 1. Formato — o mínimo, e não resolve sozinho
[Seção intitulada “1. Formato — o mínimo, e não resolve sozinho”](#1-formato--o-mínimo-e-não-resolve-sozinho)
Um campo `type="email"` com `required` já recusa o que não tem a forma de um e-mail. Não detecta domínio inexistente nem erro de digitação em domínio válido (`gmial.com` passa como formato correto) — é filtro de digitação grosseira, não de existência.
### 2. Confirmação por link — o que resolve de verdade
[Seção intitulada “2. Confirmação por link — o que resolve de verdade”](#2-confirmação-por-link--o-que-resolve-de-verdade)
A técnica mais eficaz não verifica o endereço: ela **prova** que alguém o lê. Em vez de liberar o cadastro na hora, envie um e-mail com um link de confirmação e só ative o cadastro quando ele for clicado.
Um endereço digitado errado nunca recebe o e-mail, nunca confirma, e nunca entra na sua lista de envio — sem gerar bounce nenhum, porque você nunca chega a enviar para ele de verdade. É o mesmo princípio da confirmação de inscrição que uma lista de e-mail marketing usa.
Esse e-mail de confirmação, por ser enviado para um endereço ainda não comprovado, é o único que vale a pena aceitar algum risco de bounce — é pequeno (um e-mail por cadastro) e é o próprio mecanismo que filtra o resto.
### 3. Verificar no seu servidor, antes de aceitar
[Seção intitulada “3. Verificar no seu servidor, antes de aceitar”](#3-verificar-no-seu-servidor-antes-de-aceitar)
Se o seu formulário tem um backend (não é só HTML estático), ele pode consultar a API do [Validador de E-mail](/ajuda/validador-de-email/validar-um-endereco/) no momento do envio, com a sua própria chave de API — ver [Chaves de API](/api/chaves-de-api/). A resposta diz se o endereço existe, se é descartável e se tem indício de erro de digitação, e você decide recusar o cadastro antes de gravá-lo.
Nunca do navegador do visitante
A chamada precisa partir do **seu servidor**, não de JavaScript no navegador: a chave de API fica exposta a qualquer pessoa que abrir o código da página, e ela debita crédito da sua conta a cada chamada — inclusive as que um script mal-intencionado fizer.
## Se você já tem uma lista com o problema
[Seção intitulada “Se você já tem uma lista com o problema”](#se-você-já-tem-uma-lista-com-o-problema)
A validação no formulário impede endereços NOVOS de entrar errados. Para limpar o que já está na lista, use o Validador de E-mail em lote: [Validar uma lista de e-mails](/ajuda/validador-de-email/validar-uma-lista/).
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Muitos cadastros nunca confirmam o link | Normal: é exatamente o filtro funcionando, retendo endereços errados ou pessoas que desistiram | Nenhuma ação — são cadastros que não deveriam gerar envio |
| A validação por API está descontando muito crédito | Cada chamada consome 1 crédito, mesmo para endereço inválido | Valide o formato (passo 1) antes de chamar a API, para não gastar crédito com `@` ausente ou campo vazio |
| Ainda chegam hard bounces depois de validar | A caixa existia na validação e foi desativada depois | Normal — validação prova o momento do cadastro, não garante o futuro |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/)
* [Validar um endereço de e-mail](/ajuda/validador-de-email/validar-um-endereco/)
* [Validar uma lista de e-mails](/ajuda/validador-de-email/validar-uma-lista/)
# Entender o resultado da validação
> O que significa cada característica que o Validador aponta e quais endereços manter na lista.
O Validador não dá uma nota única: ele responde **Sim** ou **Não** para cada característica do endereço. A combinação delas é o que diz se vale a pena enviar.
## Resultado da Validação
[Seção intitulada “Resultado da Validação”](#resultado-da-validação)
| Característica | Quando é **Sim** | Envie? |
| --------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Válido** | O endereço existe e o servidor do destino aceita e-mail para ele | Sim — se nada abaixo pedir cuidado |
| **Descartável** | É um e-mail temporário, desses criados para usar uma vez | Não |
| **Gratuito** | É de um provedor gratuito (Gmail, Outlook, Yahoo…) | Sim — é só uma informação |
| **Armadilha** (spam trap) | O endereço é usado para identificar quem envia para listas de baixa qualidade | Não — e revise de onde a lista veio |
| **Catch-all** | O domínio aceita qualquer endereço, exista a caixa ou não | Com cautela — não dá para confirmar que a pessoa existe |
| **Gibberish** (sem sentido) | A parte antes do `@` parece digitada ao acaso | Não |
| **Erro de digitação** | O domínio parece um erro, como `gmial.com` | Não — corrija se souber o certo |
## Classificação
[Seção intitulada “Classificação”](#classificação)
| Característica | Quando é **Sim** |
| ---------------- | --------------------------------------------------------------------------- |
| **Nome pessoal** | A parte antes do `@` parece o nome de uma pessoa |
| **Função/papel** | É um endereço de setor ou função, como `contato@`, `vendas@`, `financeiro@` |
| **Banco** | O domínio é de uma instituição financeira |
| **Governo** | O domínio é de um órgão público |
Essas características não dizem se o endereço é bom ou ruim — servem para segmentar. Endereços de função, por exemplo, costumam ser lidos por várias pessoas e engajar menos.
## Detalhes Técnicos
[Seção intitulada “Detalhes Técnicos”](#detalhes-técnicos)
**Servidor MX** é o servidor que recebe os e-mails do domínio. **Resposta SMTP** é o que esse servidor respondeu na verificação. Úteis para entender um resultado inesperado.
O atalho
Na validação de lista, **Exportar Válidos** já aplica o critério: mantém os válidos que não são descartáveis, sem sentido, armadilha nem erro de digitação.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------------------------ |
| Um endereço que você sabe que existe saiu **inválido** | O servidor do destino recusou a verificação naquele momento | Valide de novo mais tarde; se repetir, confira a **Resposta SMTP** |
| Na exportação aparece `unknow` | Não foi possível determinar aquela característica | Trate como incerto: na dúvida, não envie |
# Validar um endereço de e-mail
> Conferir um endereço antes de enviar — se existe, se é descartável, se tem erro de digitação.
A verificação avulsa confere um endereço de cada vez: se ele existe e recebe e-mail, e se tem alguma característica que pede cuidado. Serve para tirar a dúvida sobre um contato específico. Para uma lista inteira, veja [Validar uma lista de e-mails](/ajuda/validador-de-email/validar-uma-lista/).
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
Cada verificação consome **1 crédito** de validação. O saldo fica em **Créditos**, no menu do painel.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do Validador, vá em **Validação → Verificação avulsa**.
2. Em **Endereço de e-mail**, digite o endereço.
3. Clique em **Validar**.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
O resultado aparece na mesma tela, com o selo **E-mail válido** ou **E-mail inválido** e três blocos: **Resultado da Validação**, **Classificação** e **Detalhes Técnicos**. Cada item responde **Sim** ou **Não** — o que cada um quer dizer está em [Entender o resultado da validação](/ajuda/validador-de-email/entender-o-resultado/).
Se não for possível concluir a verificação, a tela informa “Não foi possível validar o e-mail.” e o crédito **não** é cobrado.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
| “Créditos insuficientes para realizar a validação.” | O saldo de validações acabou | Compre créditos no portal do cliente, em **Financeiro → Planos Disponíveis** |
| “Não foi possível consultar seus créditos no momento.” | Falha momentânea ao consultar o saldo | Tente de novo em instantes |
| “Não foi possível validar o e-mail.” | O servidor do destino não respondeu de forma conclusiva | Tente mais tarde; o crédito não foi cobrado |
| O endereço é recusado antes de validar | Formato inválido (falta `@`, espaço, caractere estranho) | Corrija a digitação |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Entender o resultado da validação](/ajuda/validador-de-email/entender-o-resultado/)
* [Validar uma lista de e-mails](/ajuda/validador-de-email/validar-uma-lista/)
# Validar uma lista de e-mails
> Enviar um arquivo CSV ou TXT, acompanhar a validação e exportar só os endereços bons.
Validar a lista antes de uma campanha tira dela os endereços que não existem, os descartáveis e as armadilhas de spam — os que geram bounce e derrubam a reputação do seu domínio.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* O arquivo deve ser **CSV** ou **TXT**, com até **50 MB** e **100.000 linhas**.
* Não precisa arrumar colunas: os e-mails são encontrados automaticamente em cada linha.
* Cada endereço validado consome **1 crédito**. Antes de aceitar o arquivo, o painel confere se o saldo cobre o número de linhas.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. No painel do Validador, vá em **Validação → Enviar arquivo**.
2. Arraste o arquivo para a área indicada, ou clique para selecioná-lo.
3. Clique em **Enviar arquivo**.
4. Acompanhe em **Validação → Arquivos enviados**. Abra o arquivo para ver o andamento; enquanto processa, a tela mostra **Processamento em andamento** — use **Verificar atualização** para ver o progresso.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* A página do arquivo mostra o **Resumo dos Resultados** — quantos válidos, inválidos, gratuitos, descartáveis, armadilhas, erros de digitação e outros — e a tabela **E-mails Validados**, linha a linha.
* **Exportar Válidos** baixa só os endereços seguros para envio: válidos e que **não** são descartáveis, sem sentido, armadilha nem erro de digitação.
* **Exportar** baixa todos, com uma coluna para cada característica.
* **Baixar original** devolve o arquivo que você enviou.
* As exportações são preparadas em segundo plano; quando o status em **Exportações** for **Concluído**, clique para baixar.
* Os resultados ficam disponíveis por **180 dias**.
O arquivo exportado é um CSV separado por **ponto e vírgula** (`;`). Nas colunas de características, `yes` quer dizer sim, `no` quer dizer não e `unknow` quer dizer que não foi possível determinar.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| “Créditos insuficientes. O arquivo possui N linhas e você possui M créditos disponíveis.” | O saldo não cobre o arquivo | Compre créditos no portal do cliente, ou divida o arquivo |
| O arquivo é recusado | Maior que 50 MB, mais de 100.000 linhas, ou formato diferente de CSV/TXT | Divida o arquivo; salve a planilha como CSV |
| Algumas linhas ficam em **Aguardando validação** por muito tempo | A verificação daquela linha não pôde ser concluída | Abra um chamado informando o arquivo |
| O CSV exportado abre todo numa coluna só no Excel | O separador é ponto e vírgula | No Excel, use **Dados → De Texto/CSV** e escolha ponto e vírgula como delimitador |
| Achei menos e-mails que linhas | Linhas sem endereço válido não entram na contagem | Confira **E-mails Encontrados** na lista de arquivos |
## Próximos passos
[Seção intitulada “Próximos passos”](#próximos-passos)
* [Entender o resultado da validação](/ajuda/validador-de-email/entender-o-resultado/)
# API — começar por aqui
> Como funciona o acesso à API da iPORTO e o que está nesta seção.
A API da iPORTO permite que o seu sistema use os serviços sem passar pelo painel.
```plaintext
Base URL https://api.iporto.com.br
Prefixo /api/external/v1
Auth Authorization: Bearer
```
## O caminho mais curto
[Seção intitulada “O caminho mais curto”](#o-caminho-mais-curto)
1. **[Chaves de API](/api/chaves-de-api/)** — pegue a sua chave e faça a primeira chamada.
2. Cadastre um **domínio e uma conta de envio** no painel do SMTP: o `from` pode ser qualquer endereço desse domínio, e a conta é quem autentica a mensagem.
3. Envie: `POST /messages` devolve **202** e o `message.tracking_code`.
4. Guarde esse código, e acompanhe por [consulta](/api/referencia/operations/messages/get/) ou por [webhook](/api/webhooks/).
Se a sua plataforma está na lista de **Guias por plataforma**, comece por lá: o guia cobre esses quatro passos já no formato dela.
## O que está nesta seção
[Seção intitulada “O que está nesta seção”](#o-que-está-nesta-seção)
| Página | O que traz |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **[Chaves de API](/api/chaves-de-api/)** | Como criar uma chave, a validade e os cuidados para guardá-la |
| **[Migrar o envio de e-mail](/api/migrar-envio-de-email/)** | A equivalência campo a campo com SendGrid, Amazon SES, Resend, Postmark e Mailgun |
| **[Referência](/api/referencia/)** | Cada endpoint, com parâmetros, respostas e exemplos em cURL, JavaScript, PHP e Python |
### Conceitos
[Seção intitulada “Conceitos”](#conceitos)
O que vale para **todos** os endpoints. Leia uma vez e você não precisa reler em cada recurso.
| Página | O que traz |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| **[Paginação](/api/conceitos/paginacao/)** | `page`, `per_page` e o `has_more` que substitui o total |
| **[Erros](/api/conceitos/erros/)** | O que cada código significa — e as distinções que mudam o seu código |
| **[Webhook e API](/api/conceitos/webhook-e-api/)** | Por que você escreve o parser uma vez só, e a receita de usar os dois juntos |
### Guias por plataforma
[Seção intitulada “Guias por plataforma”](#guias-por-plataforma)
O mesmo caminho, no dialeto da sua stack: onde guardar a chave, como enviar, como tratar cada recusa e como receber o evento de entrega.
| Página | O que traz |
| ---------------------------------- | ----------------------------------------------------------------------------------- |
| **[Laravel](/api/guias/laravel/)** | Cliente com o `Http` do framework, tratamento de recusa e rota de webhook |
| **[Node.js](/api/guias/node/)** | `fetch` nativo, sem dependência, e endpoint Express para o evento |
| **[Python](/api/guias/python/)** | `requests` com sessão, e endpoint Flask para o evento |
| **[n8n](/api/guias/n8n/)** | Nó HTTP Request, Switch por código de recusa e nó Webhook |
| **[Lovable](/api/guias/lovable/)** | A chave como secret, o pedido pronto para a função de backend e os e-mails de login |
Não achou a sua? O caminho é o mesmo em qualquer stack, e a [Referência](/api/referencia/) traz cada chamada em cURL, JavaScript, PHP e Python.
### Webhook
[Seção intitulada “Webhook”](#webhook)
O webhook é o caminho contrário da API: em vez de o seu sistema perguntar, a iPORTO avisa. Ele funciona **sem chave de API** — quem configura é o painel, e o que você precisa é de um endereço que receba `POST`.
| Página | O que traz |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **[Receber eventos](/api/webhooks/)** | Configurar o endereço que recebe os eventos das suas mensagens, e o que chega em cada envio |
| **[Os eventos e seus corpos](/api/webhooks/eventos/)** | A lista de eventos por canal e o JSON de cada um |
| **[Verificar a assinatura](/api/webhooks/verificar-assinatura/)** | Confirmar que o evento veio da iPORTO, com código em PHP e Node.js |
| **[Repetição e falhas](/api/webhooks/repeticao-e-falhas/)** | O que acontece quando o seu endereço não responde, e como acompanhar cada disparo |
O canal de SMS é liberado por conta
O envio de SMS está na [Referência → Mensagens](/api/referencia/operations/tags/mensagens/), e o canal precisa ser liberado para a sua conta antes de integrar — abra um chamado no portal do cliente, em **Suporte → Abrir Chamado**. Conta sem liberação tem o envio aceito e a mensagem não sai.
O mesmo objeto nos dois lugares
O que a consulta de mensagens devolve é **idêntico** ao que o webhook entrega em `param.details` (v1) ou `data` (v2). Você escreve o parser uma vez e usa nos dois — ver [Webhook e API](/api/conceitos/webhook-e-api/).
## Envio de e-mail sem API
[Seção intitulada “Envio de e-mail sem API”](#envio-de-e-mail-sem-api)
Para o e-mail transacional, não é preciso API: qualquer sistema que envia e-mail por SMTP — loja, ERP, CRM, aplicação própria — pode usar o servidor da iPORTO com usuário e senha. Veja [Conectar seu sistema ao servidor SMTP](/ajuda/smtp/conectar-seu-sistema/).
Procurando como fazer no painel?
Se a pergunta é “onde clico para isso”, a resposta está em [Ajuda](/ajuda/). A busca no topo cobre as duas seções.
# Criar uma chave de API
> Gerar a chave que autentica o seu sistema na API da iPORTO, escolher a validade e guardá-la com segurança.
A chave de API é a credencial que o seu sistema envia em cada requisição para provar que fala em nome da sua conta. Ela dá acesso amplo à conta — trate-a como uma senha.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
1. Abra o painel de um serviço que tenha o item **Chaves de API** no menu — **SMTP**, **Marketing**, **Validador de E-mail** ou **Prospecção**. A chave vale para a conta, não só para aquele serviço.
2. Vá em **Chaves de API** e clique em **Nova chave**.
3. Em **Nome da chave**, identifique onde ela será usada — por exemplo, `ERP produção`.
4. Em **Validade**, escolha **90**, **180** ou **360 dias**.
5. Clique em **Criar chave**.
6. Na tela seguinte, copie o **Token** com o botão **Copiar** e guarde-o num cofre de senhas ou na configuração segura do seu sistema.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
* O token vai no cabeçalho de cada requisição:
```plaintext
Authorization: Bearer SEU_TOKEN
```
* A chave para de funcionar na data de validade. Antes disso, crie uma nova, troque no seu sistema e só então pare de usar a antiga.
## Cuidados
[Seção intitulada “Cuidados”](#cuidados)
* Use a chave **só no servidor**. Nunca a coloque em código que roda no navegador ou em aplicativo, nem em repositório de código.
* Crie **uma chave por sistema**: fica fácil saber qual sistema usa qual chave.
* Prefira a **menor validade** que funcione para você.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| A API responde **401** — “Credencial de acesso ausente, inválida ou expirada” | Chave vencida, copiada pela metade, ou sem o `Bearer `antes | Confira o cabeçalho `Authorization: Bearer SEU_TOKEN`; se a chave venceu, crie outra |
| A API responde **422** — “Você não possui um plano ativo…” | A conta não tem plano ativo do serviço | Confira a assinatura no portal do cliente |
| A API responde **429** — “Muitas tentativas” | Limite de requisições por minuto atingido | Espere o tempo indicado no cabeçalho `Retry-After` e reduza o ritmo |
| A chave vazou | Ela foi exposta em código, log ou mensagem | Abra um chamado no portal do cliente **imediatamente**, em **Suporte → Abrir Chamado** |
# Erros
> O que cada código de resposta da API significa e o que fazer com ele — incluindo os que separam "conserte o pedido" de "tente de novo".
Todo erro vem em JSON, com uma frase em `error`:
```json
{ "error": "Recurso não encontrado." }
```
Quando o problema é de campo, vem também o mapa por campo, em `errors` — um para quem está lendo, o outro para quem automatiza.
## A tabela
[Seção intitulada “A tabela”](#a-tabela)
| Código | O que significa | O que fazer |
| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
| **401** | a chave não foi enviada, ou venceu | confira o cabeçalho `Authorization`; a chave dura um ano |
| **402** | o pedido está correto, falta crédito | é aviso para o financeiro, não defeito no seu código — **não** fique repetindo |
| **404** | o recurso não existe **ou** não é da sua conta | confira o identificador |
| **413** | a entrada passou do tamanho aceito | a mensagem traz o teto e o tamanho recebido |
| **422** | um parâmetro recebeu valor inválido | a resposta diz qual, em `errors` |
| **429** | requisições demais em pouco tempo | espere e repita |
| **503** | uma dependência nossa não respondeu | **tente de novo** — o pedido pode dar certo sem você mudar nada |
## Três distinções que mudam o seu código
[Seção intitulada “Três distinções que mudam o seu código”](#três-distinções-que-mudam-o-seu-código)
**402** não é **422**
`422` diz “o seu pedido está malformado, conserte-o” — é defeito no seu lado. `402` diz “o pedido está correto, falta crédito”. Tratar um como o outro produz um laço de retentativa que nunca vai dar certo.
**503** nunca vira “sem crédito”
Quando o serviço de crédito não responde, nós **não sabemos** se você tem saldo. Dizer “sem crédito” por não conseguir perguntar mandaria você comprar algo que talvez já tenha. `503` significa “tente de novo”, que é exatamente o que você deve fazer.
“não existe” e “não é sua” respondem igual, de propósito
Os dois casos devolvem **404**. Um `403` para “existe, mas não é sua” confirmaria a quem perguntou que o identificador é válido — e transformaria a rota num jeito de descobrir identificadores de terceiros.
## Erro de filtro não é silêncio
[Seção intitulada “Erro de filtro não é silêncio”](#erro-de-filtro-não-é-silêncio)
Valor inválido em filtro responde **422**. `channel=emial` **não** devolve a lista de e-mail como se o filtro tivesse funcionado.
É a diferença entre um erro que você vê na hora e uma conclusão errada que você leva meses para descobrir — “a minha conta não tem o que eu procuro”.
## Quando a lista vem vazia e não é erro
[Seção intitulada “Quando a lista vem vazia e não é erro”](#quando-a-lista-vem-vazia-e-não-é-erro)
Resposta **200** com `data` vazio tem duas causas comuns, e nenhuma é falha:
* **O registro ainda não foi arquivado.** O arquivamento tem atraso; para saber no momento do evento, use o [webhook](/api/webhooks/).
* **Saiu da janela de retenção.** Cada mensagem é guardada pelo prazo configurado no domínio que a enviou, e depois sai do histórico. O prazo aparece no painel, em **Domínios**.
Se você precisa de retenção mais longa, guarde o que o webhook entrega
Ele chega no momento do evento, com o mesmo conteúdo da resposta da consulta — ver [Webhook e API são o mesmo objeto](/api/conceitos/webhook-e-api/).
## 500
[Seção intitulada “500”](#500)
Se acontecer, não é você. A resposta é genérica de propósito: detalhe de exceção não sai para fora. Se persistir, fale com o suporte com o horário e o que você chamou.
# Paginação
> Como percorrer uma lista inteira da API — page, per_page e o has_more que substitui o total.
Toda rota que devolve lista na API usa os mesmos dois parâmetros e o mesmo bloco `meta`.
| Parâmetro | O que faz |
| ---------- | --------------------------------------------------------- |
| `page` | a página, começando em **1** |
| `per_page` | quantos itens por página — até **100**; o padrão é **25** |
```json
{
"object": "list",
"data": [ "…" ],
"meta": {
"page": 1,
"per_page": 25,
"has_more": true
}
}
```
## Percorrer tudo
[Seção intitulada “Percorrer tudo”](#percorrer-tudo)
Avance `page` enquanto `meta.has_more` for `true`:
```php
$pagina = 1;
do {
$resposta = consultar([
'sent_since' => '2026-10-01',
'per_page' => 100,
'page' => $pagina,
]);
foreach ($resposta['data'] as $item) {
processar($item);
}
$pagina++;
} while ($resposta['meta']['has_more']);
```
Por que não existe `total`
Contar quantos itens a sua conta tem exigiria varrer o histórico inteiro a cada requisição, e isso deixaria a consulta lenta para você e para todo mundo. `has_more` responde a pergunta que a paginação de fato faz — “tem próxima página?” — sem esse custo.
## Valor fora da faixa não quebra a chamada
[Seção intitulada “Valor fora da faixa não quebra a chamada”](#valor-fora-da-faixa-não-quebra-a-chamada)
`per_page` acima de 100 é reduzido para 100; zero ou negativo volta para o padrão de 25. A resposta diz, em `meta.per_page`, qual valor foi aplicado — confira ali em vez de supor que o que você mandou foi aceito.
Página muito alta devolve lista vazia, não erro
Pedir uma página além do fim responde **200** com `data` vazio e `has_more: false`. Um laço que pare por `has_more` termina sozinho; um que conte páginas por conta própria, não.
# Webhook e API são o mesmo objeto
> O que o webhook entrega e o que a consulta devolve têm o mesmo formato — você escreve o parser uma vez. E a receita de usar os dois juntos.
Cada item que a consulta devolve é **idêntico** ao que o webhook manda em `param.details` (formato v1) ou em `data` (formato v2).
Isso não é coincidência de desenho: os dois saem do mesmo objeto, do nosso lado. Quem já trata o webhook já sabe ler a resposta da consulta, e vice-versa — **você escreve o parser uma vez.**
Os campos de `message`, `delivery` e `engagement` estão descritos em [O bloco `param.details`](/api/webhooks/eventos/#o-bloco-paramdetails).
## Quando usar cada um
[Seção intitulada “Quando usar cada um”](#quando-usar-cada-um)
| | |
| ------------ | ----------------------------------------------------------------- |
| **Webhook** | você quer saber **no momento** em que acontece |
| **Consulta** | você quer o estado **agora**, ou o motivo de uma falha específica |
O webhook avisa; a consulta responde o detalhe. O caminho mais comum de integração usa os dois.
## A receita
[Seção intitulada “A receita”](#a-receita)
```javascript
// 1. O seu endpoint recebe o evento e responde 2xx IMEDIATAMENTE.
app.post('/webhook/iporto', (req, res) => {
res.sendStatus(200);
// 2. O processamento acontece depois, fora do ciclo da resposta.
fila.enfileirar(req.body);
});
// 3. No processamento, o código de rastreio liga o evento à sua mensagem.
async function processar(evento) {
// v1: param.message_tracking_code · v2: data.message.tracking_code
const codigo = evento.param?.message_tracking_code ?? evento.data?.message?.tracking_code;
const pedido = await meuBanco.acharPorCodigo(codigo);
// 4. O detalhe já vem NO evento — `param.details` (v1) ou `data` (v2).
// A consulta só é necessária quando você quer o motivo do bounce.
const detalhe = evento.param?.details ?? evento.data;
await pedido.atualizar({ status: detalhe.delivery.status });
}
```
Responda 2xx antes de processar
O endpoint tem **15 segundos**. Processamento pesado dentro da resposta estoura o prazo, e o evento é reenviado — ver [Repetição e falhas](/api/webhooks/repeticao-e-falhas/).
## Uma diferença, e ela é de propósito
[Seção intitulada “Uma diferença, e ela é de propósito”](#uma-diferença-e-ela-é-de-propósito)
Na resposta da consulta, o bloco `event` vem **nulo**.
Uma consulta não é um evento. Preencher aquele bloco daria a você um identificador que não corresponde a nenhum webhook recebido, e um horário que é o da sua consulta — dois dados que parecem úteis e levam a conciliação errada.
A chave continua existindo para o formato ser o mesmo nos dois lugares. Se você quer eventos, use o [webhook](/api/webhooks/).
# Integrar com Laravel
> Integrar Laravel à iPORTO: enviar e-mail e SMS, tratar recusa e acompanhar a entrega.
Antes de começar
Dificuldade: Fácil | Tempo estimado: \~30 min
O catálogo de campos e códigos está na [Referência](/api/referencia/).
## O que este guia cobre
[Seção intitulada “O que este guia cobre”](#o-que-este-guia-cobre)
* Enviar e-mail e SMS pela API, com o cliente HTTP que já vem no Laravel
* Guardar o código de rastreio junto do seu registro
* Tratar as recusas sem um `try` genérico que engole tudo
* Acompanhar a entrega, por consulta ou por webhook
## Pré-requisitos
[Seção intitulada “Pré-requisitos”](#pré-requisitos)
* Laravel 10 ou 11
* Uma chave de API — ver [Chaves de API](/api/chaves-de-api/)
* Um domínio e ao menos uma conta de envio nele, no painel do SMTP
***
## Passo 1: Credenciais (5 min)
[Seção intitulada “Passo 1: Credenciais (5 min)”](#passo-1-credenciais-5-min)
No `.env`:
```bash
IPORTO_API_URL=https://api.iporto.com.br/api/external/v1
IPORTO_API_KEY=sua_chave_aqui
IPORTO_MAIL_FROM="Loja "
```
Em `config/services.php`:
```php
'iporto' => [
'url' => env('IPORTO_API_URL'),
'key' => env('IPORTO_API_KEY'),
'from' => env('IPORTO_MAIL_FROM'),
],
```
O `from` precisa ser de um domínio seu
Qualquer endereço de um domínio cadastrado no painel do SMTP serve — não precisa ser uma conta. Domínio que não é seu é recusado com **422**: sem ele cadastrado não há assinatura DKIM, e a mensagem cai em spam. Subdomínio é cadastrado como domínio próprio.
***
## Passo 2: O client (10 min)
[Seção intitulada “Passo 2: O client (10 min)”](#passo-2-o-client-10-min)
Uma classe só, com o token e a base já resolvidos:
```php
withToken(config('services.iporto.key'))
->acceptJson()
// 10s cobre o aceite com folga: o envio em si acontece depois, na fila.
->timeout(10)
->when($idempotencyKey, fn ($http) => $http->withHeader('Idempotency-Key', $idempotencyKey))
->post('/messages', $payload);
}
public function find(string $trackingCode): Response
{
return Http::baseUrl(config('services.iporto.url'))
->withToken(config('services.iporto.key'))
->acceptJson()
->get("/messages/{$trackingCode}");
}
}
```
Não use `->throw()` aqui
Ele transforma 402, 422 e 429 na mesma exceção, e as três pedem ações diferentes. O passo 4 trata uma por uma.
***
## Passo 3: Enviar, e guardar o código (5 min)
[Seção intitulada “Passo 3: Enviar, e guardar o código (5 min)”](#passo-3-enviar-e-guardar-o-código-5-min)
```php
$resposta = app(IportoMessages::class)->send([
'from' => config('services.iporto.from'),
'to' => [$pedido->cliente_email],
'subject' => "Seu pedido {$pedido->numero}",
'html' => view('emails.pedido-confirmado', ['pedido' => $pedido])->render(),
'tags' => ['transacional', "pedido-{$pedido->numero}"],
], idempotencyKey: "pedido-{$pedido->numero}");
if ($resposta->successful()) {
$pedido->update([
'iporto_tracking_code' => $resposta->json('message.tracking_code'),
]);
}
```
A resposta é **202**, não 200
`$resposta->successful()` cobre a faixa 2xx e funciona. Já `$resposta->status() === 200` nunca é verdadeiro: 202 quer dizer “aceita, e sai em seguida pela fila”.
A `Idempotency-Key` é o que torna a retentativa segura
Se a requisição falhou por tempo esgotado e você não sabe se chegou, repita com a mesma chave: ou recebe a mensagem que já existe, ou ela é criada agora — nunca duas. Com corpo diferente e a mesma chave, a resposta é 422.
***
## Passo 4: Tratar a recusa (5 min)
[Seção intitulada “Passo 4: Tratar a recusa (5 min)”](#passo-4-tratar-a-recusa-5-min)
```php
$resposta = app(IportoMessages::class)->send($payload, "pedido-{$pedido->numero}");
if ($resposta->successful()) {
$pedido->update(['iporto_tracking_code' => $resposta->json('message.tracking_code')]);
return;
}
match ($resposta->status()) {
// Sem crédito: avise quem compra, não repita.
402 => Notification::route('mail', config('mail.admin'))->notify(new SemCreditoNaIporto),
// Corpo acima de 16 MB: mande o anexo por `url` em vez de base64.
413 => Log::warning('[iPORTO] Mensagem grande demais', ['pedido' => $pedido->id]),
// Campo inválido. `errors` diz qual — não adivinhe.
422 => Log::error('[iPORTO] Recusa de validação', ['errors' => $resposta->json('errors')]),
// Acima de 8.000 por minuto. `Retry-After` diz quantos segundos esperar.
429 => $this->release((int) $resposta->header('Retry-After') ?: 60),
default => Log::error('[iPORTO] Falha inesperada', ['status' => $resposta->status()]),
};
```
Os códigos, com as distinções que mudam o seu código, estão em [Erros](/api/conceitos/erros/).
***
## Passo 5: Acompanhar a entrega (5 min)
[Seção intitulada “Passo 5: Acompanhar a entrega (5 min)”](#passo-5-acompanhar-a-entrega-5-min)
Duas formas, e a segunda é a que não gasta requisição.
**Consultando**, quando você precisa saber agora:
```php
$status = app(IportoMessages::class)
->find($pedido->iporto_tracking_code)
->json('delivery.status');
// msg:yes:queue · msg:yes:delivered · msg:yes:finished[:with:bounce|filter|trap] · msg:not:undelivered
```
**Recebendo o evento**, que é o caminho normal. Configure o endereço no painel e exponha uma rota:
```php
// routes/api.php — sem o middleware `auth`, e com o segredo conferido no controller.
Route::post('/webhooks/iporto', IportoWebhookController::class);
```
```php
public function __invoke(Request $request)
{
// A verificação da assinatura está em /api/webhooks/verificar-assinatura/
$evento = $request->input('event');
$codigo = $request->input('param.message_tracking_code');
Pedido::where('iporto_tracking_code', $codigo)->update([
'email_status' => $request->input('param.details.delivery.status'),
]);
return response()->json(['ok' => true]);
}
```
O mesmo objeto nos dois lugares
O que a consulta devolve é **idêntico** ao que o webhook entrega em `param.details`. Você escreve o parser uma vez — ver [Webhook e API](/api/conceitos/webhook-e-api/).
***
## Passo 6: SMS (opcional — 2 min)
[Seção intitulada “Passo 6: SMS (opcional — 2 min)”](#passo-6-sms-opcional--2-min)
Mesmo endpoint, com `channel`:
```php
app(IportoMessages::class)->send([
'channel' => 'sms',
'to' => preg_replace('/\D/', '', $pedido->cliente_telefone),
'text' => "Seu pedido {$pedido->numero} foi confirmado.",
]);
```
O canal de SMS é liberado por conta
Sem a liberação, o envio é aceito e a mensagem não sai. Abra um chamado no portal do cliente, em **Suporte → Abrir Chamado**, antes de integrar o SMS.
***
## Passo 7: Testes (5 min)
[Seção intitulada “Passo 7: Testes (5 min)”](#passo-7-testes-5-min)
```php
it('guarda o código de rastreio quando a iPORTO aceita', function () {
Http::fake([
'*/messages' => Http::response([
'message' => ['tracking_code' => '3f2a7c18-9d4e-4b6a-8c1f-5e2d7a0b3f49'],
], 202),
]);
$pedido = Pedido::factory()->create();
(new EnviarConfirmacao)->handle($pedido);
expect($pedido->fresh()->iporto_tracking_code)->not->toBeNull();
});
```
**Checklist:**
* [ ] O envio devolve 202 e o código de rastreio fica gravado
* [ ] Repetir com a mesma `Idempotency-Key` não cria uma segunda mensagem
* [ ] Um `from` que não é seu devolve 422 e o erro aparece no log com o campo
* [ ] 429 reenfileira em vez de descartar
* [ ] A rota de webhook responde 200 e atualiza o seu registro
***
Catálogo completo de campos e códigos: [Referência](/api/referencia/).
# Integrar com Lovable
> Enviar e-mail de um app feito no Lovable pela API da iPORTO: a chave como secret, o pedido pronto para a função de backend, o teste no histórico e onde ficam os e-mails de login.
Antes de começar
Dificuldade: Fácil | Tempo estimado: \~15 min
O catálogo de campos e códigos está na [Referência](/api/referencia/).
## O que este guia cobre
[Seção intitulada “O que este guia cobre”](#o-que-este-guia-cobre)
* Guardar a chave da iPORTO como secret do projeto, longe do navegador
* Pedir ao Lovable a função de backend que envia — com o texto pronto para colar no chat
* Testar o envio e conferir no histórico
* Onde ficam os e-mails de login (cadastro, recuperação de senha)
No Lovable você não escreve a função: descreve o que precisa no chat, e ele cria, publica e mantém a função de backend (*edge function*). Por isso este guia gira em torno do **pedido** — é ele que define se a chave fica protegida e quem pode receber os seus e-mails.
## Pré-requisitos
[Seção intitulada “Pré-requisitos”](#pré-requisitos)
* Um projeto no Lovable com o backend ativo — Lovable Cloud ou um Supabase próprio
* Uma chave de API — ver [Chaves de API](/api/chaves-de-api/)
* Um domínio e ao menos uma conta de envio nele, no painel do SMTP
***
## Passo 1: A chave (3 min)
[Seção intitulada “Passo 1: A chave (3 min)”](#passo-1-a-chave-3-min)
Crie uma chave só para este app, com um nome que diga onde ela está — por exemplo, `Lovable — site`. Copie o **Token** e deixe à mão para o passo 2.
Nunca cole a chave no texto do chat
O Lovable pede a chave numa caixa própria, **Add secret**, e a guarda como secret: ela fica no backend e nunca chega ao navegador. Colada no meio de uma mensagem, ela fica no histórico da conversa.
***
## Passo 2: Pedir a função (5 min)
[Seção intitulada “Passo 2: Pedir a função (5 min)”](#passo-2-pedir-a-função-5-min)
Cole no chat do projeto, trocando o remetente e o destinatário pelos seus:
```text
Crie uma página de contato com os campos Nome, E-mail e Mensagem.
Ao enviar, chame uma edge function chamada send-contact-email que:
- leia a chave da API do secret IPORTO_API_KEY, só no backend, nunca no frontend;
- faça POST para https://api.iporto.com.br/api/external/v1/messages com os cabeçalhos
Authorization: Bearer , Content-Type: application/json e Accept: application/json;
- envie o corpo JSON:
from: "Sua Empresa "
to: ["voce@seudominio.com.br"] (fixo no código, nunca vindo do formulário)
reply_to: [o e-mail digitado pelo visitante]
subject: "Contato pelo site: "
html: nome, e-mail e mensagem, com o HTML escapado;
- trate como sucesso só a resposta 202 e devolva o message.tracking_code;
- em qualquer outro status, registre no log o status e o corpo da resposta e devolva erro.
Mostre "Mensagem enviada" ou "Não foi possível enviar" para o visitante.
```
Quando o Lovable pedir a chave, a caixa **Add secret** aparece no chat: cole o token e clique em **Submit**. Se preferir cadastrar antes, o caminho é **More → Settings → Secrets → Add secret**, com o nome `IPORTO_API_KEY`. É nessa mesma tela que a chave aparece depois, na lista de secrets.
**O que cada linha do pedido garante:**
| Linha | Por quê |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| A chave só no backend | Chave no código do navegador fica visível para qualquer visitante — e ela dá acesso à sua conta |
| `to` fixo no código | Se o destinatário viesse do formulário, qualquer pessoa usaria o seu app para enviar e-mail em nome do seu domínio, com o seu crédito |
| `reply_to` com o e-mail do visitante | O **Responder** do seu programa de e-mail vai direto para quem escreveu |
| HTML escapado | O que o visitante digita aparece como texto, e não vira HTML dentro do seu e-mail |
| Sucesso só no 202 | 202 é “aceita, e sai em seguida pela fila” — ver [Erros](/api/conceitos/erros/) |
Enquanto constrói, o Lovable pode testar a função — e o teste é um envio de verdade
Um e-mail pode chegar antes de você usar o formulário. Ele aparece no histórico e conta no seu crédito como qualquer outro.
***
## Passo 3: Testar (3 min)
[Seção intitulada “Passo 3: Testar (3 min)”](#passo-3-testar-3-min)
1. No **Preview**, preencha o formulário com um e-mail seu e clique em enviar.
2. A tela mostra **Mensagem enviada**.
3. Abra o painel do SMTP e confira o envio em [Histórico de envio](/ajuda/smtp/consultar-o-historico-de-envio/).
4. No e-mail recebido, clique em **Responder**: o destinatário é o e-mail digitado no formulário.
***
## Passo 4: Os outros e-mails do app (opcional)
[Seção intitulada “Passo 4: Os outros e-mails do app (opcional)”](#passo-4-os-outros-e-mails-do-app-opcional)
Confirmação de pedido, aviso de agendamento, boas-vindas: o pedido é o mesmo, mudando o gatilho e de onde vem o destinatário. Exemplos:
```text
Quando um pedido for criado, use a edge function de envio da iPORTO para mandar a confirmação
ao e-mail do cliente gravado no pedido.
```
```text
Quando um agendamento for confirmado, envie pela API da iPORTO um e-mail para o cliente do
agendamento e uma cópia para agenda@seudominio.com.br.
```
O destinatário vem do banco ou do código — nunca do navegador
A função de backend pode ser chamada por qualquer pessoa que abra o seu app. Se ela aceita o destinatário e o conteúdo vindos do navegador, ela vira um envio aberto em nome do seu domínio. Deixe a função buscar o destinatário no registro (o pedido, o agendamento, o usuário logado).
***
## E-mails de login
[Seção intitulada “E-mails de login”](#e-mails-de-login)
Cadastro, confirmação de e-mail e recuperação de senha não passam por esta função: quem envia é o sistema de login do backend.
* **Lovable Cloud:** os e-mails de login saem pelo próprio Lovable, e não há onde configurar SMTP.
* **Supabase próprio:** configure o SMTP da iPORTO no Supabase — veja [Configurar SMTP no Supabase](/ajuda/smtp/plataformas/supabase/).
***
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
O formulário só diz **Não foi possível enviar**. O histórico do painel do SMTP separa os casos: se o envio não aparece lá, a API recusou o pedido antes de enviar.
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Não foi possível enviar**, e nada aparece no histórico | A chave foi revogada, venceu ou foi colada pela metade — o caso mais comum. Ou o remetente não é de um domínio cadastrado, ou falta crédito | Em **Chaves de API**, confira se a chave está ativa e na validade; se não, crie outra e troque o valor em **More → Settings → Secrets** (o valor não pode ser lido de volta: substitua). Confira também se o `from` é de um domínio cadastrado no painel do SMTP e o saldo no portal do cliente |
| Depois de trocar a chave, o **Preview** envia e o app publicado não | A troca de secret vale na hora no **Preview**, mas só chega ao app publicado depois de publicar | Publique o app de novo |
| **Responder** vai para o seu próprio endereço | A função não envia o `reply_to` | Peça ao Lovable para incluir o `reply_to` com o e-mail do visitante |
| Aparecem no histórico e-mails que ninguém do seu time enviou | A função aceita destinatário vindo do navegador | Peça ao Lovable para fixar o destinatário no código ou buscá-lo no banco |
Os códigos de recusa da API estão em [Erros](/api/conceitos/erros/).
***
**Checklist:**
* [ ] A chave está em **Secrets**, e não no código nem no chat
* [ ] O formulário mostra **Mensagem enviada**, e o envio aparece no histórico
* [ ] **Responder** vai para o e-mail do visitante
* [ ] Com a chave errada, o formulário mostra **Não foi possível enviar**, e nada entra no histórico
* [ ] Nenhuma função aceita destinatário vindo do navegador
***
Catálogo completo de campos e códigos: [Referência](/api/referencia/).
# Integrar com n8n
> Integrar n8n à iPORTO: enviar e-mail e SMS, tratar recusa e acompanhar a entrega.
Antes de começar
Dificuldade: Fácil | Tempo estimado: \~30 min
O catálogo de campos e códigos está na [Referência](/api/referencia/).
## O que este guia cobre
[Seção intitulada “O que este guia cobre”](#o-que-este-guia-cobre)
* Enviar e-mail e SMS pelo nó **HTTP Request**, sem escrever código
* Guardar o código de rastreio no passo seguinte do fluxo
* Ramificar por código de recusa com o nó **Switch**
* Receber o evento de entrega pelo nó **Webhook**
## Pré-requisitos
[Seção intitulada “Pré-requisitos”](#pré-requisitos)
* Uma instância do n8n, na nuvem ou própria
* Uma chave de API — ver [Chaves de API](/api/chaves-de-api/)
* Um domínio e ao menos uma conta de envio nele, no painel do SMTP
* Para o webhook: uma URL do n8n alcançável pela internet
***
## Passo 1: Credenciais (5 min)
[Seção intitulada “Passo 1: Credenciais (5 min)”](#passo-1-credenciais-5-min)
Guarde a chave como credencial, para ela não ficar escrita em cada nó:
* **Settings → Credentials → New Credential → Header Auth**
* Name: `iPORTO API`
* Header Name: `Authorization`
* Header Value: `Bearer sua_chave_aqui`
O `from` precisa ser de um domínio seu
Qualquer endereço de um domínio cadastrado no painel do SMTP serve — não precisa ser uma conta. Domínio que não é seu é recusado com **422**: sem ele cadastrado não há assinatura DKIM, e a mensagem cai em spam. Subdomínio é cadastrado como domínio próprio.
***
## Passo 2: O nó que envia (10 min)
[Seção intitulada “Passo 2: O nó que envia (10 min)”](#passo-2-o-nó-que-envia-10-min)
Acrescente um nó **HTTP Request** com esta configuração:
```plaintext
Method: POST
URL: https://api.iporto.com.br/api/external/v1/messages
Authentication: Predefined Credential Type → Header Auth → "iPORTO API"
Send Body: on
Body Content Type: JSON
Specify Body: Using JSON
JSON:
{
"from": "Loja ",
"to": ["{{ $json.cliente_email }}"],
"subject": "Seu pedido {{ $json.numero }}",
"html": "Seu pedido {{ $json.numero }} foi confirmado.
",
"tags": ["transacional", "pedido-{{ $json.numero }}"]
}
Options → Response → Include Response Headers and Status: on
Options → Response → Never Error: on
```
Ligue “Never Error” e “Include Response Headers and Status”
Sem o primeiro, o n8n derruba a execução em 402, 422 e 429, e você perde o corpo da resposta — que é justamente onde está o motivo. Sem o segundo, não dá para ramificar por código no passo 4.
`to` é sempre uma lista
Mesmo com um destinatário só. `"to": "{{ $json.cliente_email }}"` sem os colchetes devolve 422.
***
## Passo 3: Guardar o código de rastreio (5 min)
[Seção intitulada “Passo 3: Guardar o código de rastreio (5 min)”](#passo-3-guardar-o-código-de-rastreio-5-min)
A resposta de sucesso é **202**, e o código vem em `body.message.tracking_code`. Acrescente um nó **Set** (ou **Edit Fields**) depois do HTTP Request:
```plaintext
Mode: Manual Mapping
Fields:
tracking_code = {{ $json.body.message.tracking_code }}
numero = {{ $('Quando chega o pedido').item.json.numero }}
```
Em seguida, grave onde o seu fluxo guarda dados — Postgres, Google Sheets, Airtable, o que for.
Guarde o `tracking_code`, não o `message.id`
Poucos minutos depois de terminar, a mensagem é arquivada e o identificador interno muda. O código de rastreio resolve nos dois momentos, e é ele que chega em todo evento de webhook.
***
## Passo 4: Ramificar por código de recusa (5 min)
[Seção intitulada “Passo 4: Ramificar por código de recusa (5 min)”](#passo-4-ramificar-por-código-de-recusa-5-min)
Acrescente um nó **Switch** depois do HTTP Request:
```plaintext
Mode: Rules
Value to Match: {{ $json.statusCode }}
Rule 1 → 202 → [gravar o tracking_code]
Rule 2 → 402 → [avisar o financeiro: sem crédito]
Rule 3 → 413 → [mandar o anexo por URL em vez de base64]
Rule 4 → 422 → [registrar {{ $json.body.errors }} e corrigir o campo]
Rule 5 → 429 → [nó Wait de {{ $json.headers['retry-after'] }}s e voltar ao HTTP Request]
Fallback → [registrar e alertar]
```
O que cada código significa está em [Erros](/api/conceitos/erros/).
422 sempre diz qual campo
`body.errors` traz o nome do campo e o motivo. Os dois mais comuns: `from` de um domínio que não é seu, e `subject` com quebra de linha. Não é preciso adivinhar.
***
## Passo 5: Não enviar duas vezes (3 min)
[Seção intitulada “Passo 5: Não enviar duas vezes (3 min)”](#passo-5-não-enviar-duas-vezes-3-min)
Se o seu fluxo pode reexecutar — e com `Retry On Fail` ligado ele pode —, acrescente o cabeçalho de idempotência no HTTP Request:
```plaintext
Options → Headers → Add Header
Name: Idempotency-Key
Value: pedido-{{ $json.numero }}
```
Repetir com a mesma chave e o mesmo corpo devolve a mensagem original e `Idempotent-Replayed: true`, sem enviar de novo. Com corpo diferente e a mesma chave, a resposta é 422.
***
## Passo 6: Receber o evento de entrega (5 min)
[Seção intitulada “Passo 6: Receber o evento de entrega (5 min)”](#passo-6-receber-o-evento-de-entrega-5-min)
Num fluxo novo, acrescente um nó **Webhook** como gatilho:
```plaintext
HTTP Method: POST
Path: iporto-eventos
Response Mode: Immediately
Response Data: { "ok": true }
```
Copie a **Webhook URL** e cadastre no painel da iPORTO. Depois, um **Switch** para separar os eventos:
```plaintext
Value to Match: {{ $json.body.event }}
email.queued → [marcar como enfileirada]
email.delivered → [marcar como entregue]
email.rejected → [tratar a recusa: {{ $json.body.param.details.delivery.bounce }}]
sms.delivered → [marcar o SMS como entregue]
```
O código de rastreio chega em `body.param.message_tracking_code`, e o objeto completo da mensagem em `body.param.details` — **o mesmo** que a consulta devolve.
Um fluxo, não dois parsers
Como o corpo do evento é idêntico ao da consulta, o mesmo mapeamento de campos serve nos dois caminhos. Ver [Webhook e API](/api/conceitos/webhook-e-api/).
A conferência da assinatura está em [Verificar a assinatura](/api/webhooks/verificar-assinatura/).
***
## Passo 7: SMS (opcional — 2 min)
[Seção intitulada “Passo 7: SMS (opcional — 2 min)”](#passo-7-sms-opcional--2-min)
Mesmo nó, outro JSON:
```json
{
"channel": "sms",
"to": "{{ $json.telefone.replace(/\\D/g, '') }}",
"text": "Seu pedido {{ $json.numero }} foi confirmado."
}
```
O canal de SMS é liberado por conta
Sem a liberação, o envio é aceito e a mensagem não sai. Abra um chamado no portal do cliente, em **Suporte → Abrir Chamado**, antes de integrar o SMS.
***
## Passo 8: Testes (5 min)
[Seção intitulada “Passo 8: Testes (5 min)”](#passo-8-testes-5-min)
Use **Execute Workflow** com um item de teste e confira no log de execução do nó.
**Checklist:**
* [ ] O HTTP Request devolve `statusCode` 202 e o `tracking_code` aparece no nó Set
* [ ] Com um `from` que não é seu, o Switch cai no ramo 422 e `body.errors.from` aparece
* [ ] Reexecutar o fluxo com a mesma `Idempotency-Key` não cria uma segunda mensagem
* [ ] O nó Webhook mostra o evento recebido no log
* [ ] O Switch do webhook roteia `email.delivered` para o ramo certo
***
Catálogo completo de campos e códigos: [Referência](/api/referencia/).
# Integrar com Node.js
> Integrar Node.js à iPORTO: enviar e-mail e SMS, tratar recusa e acompanhar a entrega.
Antes de começar
Dificuldade: Fácil | Tempo estimado: \~25 min
O catálogo de campos e códigos está na [Referência](/api/referencia/).
## O que este guia cobre
[Seção intitulada “O que este guia cobre”](#o-que-este-guia-cobre)
* Enviar e-mail e SMS com o `fetch` nativo, sem dependência nenhuma
* Guardar o código de rastreio junto do seu registro
* Tratar cada recusa pelo que ela significa
* Receber o evento de entrega num endpoint Express
## Pré-requisitos
[Seção intitulada “Pré-requisitos”](#pré-requisitos)
* Node.js 18 ou mais novo (o `fetch` é nativo a partir dele)
* Uma chave de API — ver [Chaves de API](/api/chaves-de-api/)
* Um domínio e ao menos uma conta de envio nele, no painel do SMTP
***
## Passo 1: Credenciais (3 min)
[Seção intitulada “Passo 1: Credenciais (3 min)”](#passo-1-credenciais-3-min)
No `.env`:
```bash
IPORTO_API_URL=https://api.iporto.com.br/api/external/v1
IPORTO_API_KEY=sua_chave_aqui
IPORTO_MAIL_FROM="Loja "
```
O `from` precisa ser de um domínio seu
Qualquer endereço de um domínio cadastrado no painel do SMTP serve — não precisa ser uma conta. Domínio que não é seu é recusado com **422**: sem ele cadastrado não há assinatura DKIM, e a mensagem cai em spam. Subdomínio é cadastrado como domínio próprio.
***
## Passo 2: O client (7 min)
[Seção intitulada “Passo 2: O client (7 min)”](#passo-2-o-client-7-min)
iporto.js
```js
const BASE = process.env.IPORTO_API_URL;
const KEY = process.env.IPORTO_API_KEY;
export async function sendMessage(payload, { idempotencyKey } = {}) {
const response = await fetch(`${BASE}/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${KEY}`,
'Content-Type': 'application/json',
Accept: 'application/json',
...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
},
body: JSON.stringify(payload),
// 10s cobre o aceite com folga: o envio acontece depois, na fila.
signal: AbortSignal.timeout(10_000),
});
return { status: response.status, body: await response.json(), headers: response.headers };
}
export async function findMessage(trackingCode) {
const response = await fetch(`${BASE}/messages/${trackingCode}`, {
headers: { Authorization: `Bearer ${KEY}`, Accept: 'application/json' },
});
return response.json();
}
```
Não use `response.ok` como única régua
Ele é verdadeiro para toda a faixa 2xx, o que está certo para o aceite — mas as recusas 402, 422 e 429 pedem ações diferentes, e `ok` as achata num só “deu erro”. O passo 4 separa.
***
## Passo 3: Enviar, e guardar o código (4 min)
[Seção intitulada “Passo 3: Enviar, e guardar o código (4 min)”](#passo-3-enviar-e-guardar-o-código-4-min)
```js
const { status, body } = await sendMessage({
from: process.env.IPORTO_MAIL_FROM,
to: [pedido.clienteEmail],
subject: `Seu pedido ${pedido.numero}`,
html: `Seu pedido ${pedido.numero} foi confirmado.
`,
tags: ['transacional', `pedido-${pedido.numero}`],
}, { idempotencyKey: `pedido-${pedido.numero}` });
if (status === 202) {
await db.pedidos.update(pedido.id, {
iportoTrackingCode: body.message.tracking_code,
});
}
```
A resposta é **202**, não 200
202 quer dizer “aceita, e sai em seguida pela fila”. Código que compara com 200 nunca entra no ramo de sucesso.
A `Idempotency-Key` é o que torna a retentativa segura
Repetir a mesma requisição com a mesma chave devolve a mensagem original e o cabeçalho `Idempotent-Replayed: true` — nada é enviado de novo. Com corpo diferente e a mesma chave, a resposta é 422.
***
## Passo 4: Tratar a recusa (4 min)
[Seção intitulada “Passo 4: Tratar a recusa (4 min)”](#passo-4-tratar-a-recusa-4-min)
```js
switch (status) {
case 202:
await db.pedidos.update(pedido.id, { iportoTrackingCode: body.message.tracking_code });
break;
// Sem crédito: avise quem compra, não repita.
case 402:
await alertarFinanceiro(body.error);
break;
// Corpo acima de 16 MB: mande o anexo por `url` em vez de base64.
case 413:
logger.warn('[iPORTO] mensagem grande demais', { pedido: pedido.id });
break;
// Campo inválido. `errors` diz qual — não adivinhe.
case 422:
logger.error('[iPORTO] recusa de validação', { errors: body.errors });
break;
// Acima de 8.000 por minuto. `Retry-After` diz quantos segundos esperar.
case 429:
await filaDeReenvio.add(pedido, { delay: Number(headers.get('retry-after') ?? 60) * 1000 });
break;
default:
logger.error('[iPORTO] falha inesperada', { status });
}
```
Os códigos, com as distinções que mudam o seu código, estão em [Erros](/api/conceitos/erros/).
***
## Passo 5: Receber o evento de entrega (5 min)
[Seção intitulada “Passo 5: Receber o evento de entrega (5 min)”](#passo-5-receber-o-evento-de-entrega-5-min)
Configure o endereço no painel e exponha a rota. O corpo cru é necessário para conferir a assinatura, então registre o parser com `raw` antes do JSON:
```js
import express from 'express';
const app = express();
app.post('/webhooks/iporto', express.raw({ type: 'application/json' }), (req, res) => {
// A verificação da assinatura está em /api/webhooks/verificar-assinatura/
const evento = JSON.parse(req.body.toString('utf8'));
const codigo = evento.param?.message_tracking_code;
const status = evento.param?.details?.delivery?.status;
db.pedidos.updateByTrackingCode(codigo, { emailStatus: status });
res.json({ ok: true });
});
```
Assine o corpo CRU, byte a byte
`express.json()` reserializa o corpo, e a assinatura deixa de casar por causa de um espaço ou da ordem das chaves. Use `express.raw()` nesta rota.
O mesmo objeto nos dois lugares
O que a consulta devolve é **idêntico** ao que o webhook entrega em `param.details` — o parser serve nos dois. Ver [Webhook e API](/api/conceitos/webhook-e-api/).
***
## Passo 6: SMS (opcional — 2 min)
[Seção intitulada “Passo 6: SMS (opcional — 2 min)”](#passo-6-sms-opcional--2-min)
```js
await sendMessage({
channel: 'sms',
to: pedido.clienteTelefone.replace(/\D/g, ''),
text: `Seu pedido ${pedido.numero} foi confirmado.`,
});
```
O canal de SMS é liberado por conta
Sem a liberação, o envio é aceito e a mensagem não sai. Abra um chamado no portal do cliente, em **Suporte → Abrir Chamado**, antes de integrar o SMS.
***
## Passo 7: Testes (4 min)
[Seção intitulada “Passo 7: Testes (4 min)”](#passo-7-testes-4-min)
**Checklist:**
* [ ] O envio devolve 202 e o código de rastreio fica gravado
* [ ] Repetir com a mesma `Idempotency-Key` devolve `Idempotent-Replayed: true`
* [ ] Um `from` que não é seu devolve 422 e `errors.from` aparece no log
* [ ] 429 reenfileira usando o `Retry-After`
* [ ] A rota de webhook responde 200 e atualiza o seu registro
```bash
curl -X POST https://api.iporto.com.br/api/external/v1/messages \
-H "Authorization: Bearer $IPORTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"Loja ","to":["voce@suaempresa.com.br"],"subject":"Teste","html":"Teste
"}'
```
***
Catálogo completo de campos e códigos: [Referência](/api/referencia/).
# Integrar com Python
> Integrar Python à iPORTO: enviar e-mail e SMS, tratar recusa e acompanhar a entrega.
Antes de começar
Dificuldade: Fácil | Tempo estimado: \~25 min
O catálogo de campos e códigos está na [Referência](/api/referencia/).
## O que este guia cobre
[Seção intitulada “O que este guia cobre”](#o-que-este-guia-cobre)
* Enviar e-mail e SMS com `requests`
* Guardar o código de rastreio junto do seu registro
* Tratar cada recusa pelo que ela significa
* Receber o evento de entrega num endpoint Flask
## Pré-requisitos
[Seção intitulada “Pré-requisitos”](#pré-requisitos)
* Python 3.9 ou mais novo
* `pip install requests`
* Uma chave de API — ver [Chaves de API](/api/chaves-de-api/)
* Um domínio e ao menos uma conta de envio nele, no painel do SMTP
***
## Passo 1: Credenciais (3 min)
[Seção intitulada “Passo 1: Credenciais (3 min)”](#passo-1-credenciais-3-min)
```bash
export IPORTO_API_URL="https://api.iporto.com.br/api/external/v1"
export IPORTO_API_KEY="sua_chave_aqui"
export IPORTO_MAIL_FROM="Loja "
```
O `from` precisa ser de um domínio seu
Qualquer endereço de um domínio cadastrado no painel do SMTP serve — não precisa ser uma conta. Domínio que não é seu é recusado com **422**: sem ele cadastrado não há assinatura DKIM, e a mensagem cai em spam. Subdomínio é cadastrado como domínio próprio.
***
## Passo 2: O client (7 min)
[Seção intitulada “Passo 2: O client (7 min)”](#passo-2-o-client-7-min)
iporto.py
```python
import os
import requests
BASE = os.environ["IPORTO_API_URL"]
KEY = os.environ["IPORTO_API_KEY"]
_session = requests.Session()
_session.headers.update({
"Authorization": f"Bearer {KEY}",
"Accept": "application/json",
})
def send_message(payload, idempotency_key=None):
headers = {"Idempotency-Key": idempotency_key} if idempotency_key else {}
# 10s cobre o aceite com folga: o envio acontece depois, na fila.
return _session.post(f"{BASE}/messages", json=payload, headers=headers, timeout=10)
def find_message(tracking_code):
return _session.get(f"{BASE}/messages/{tracking_code}", timeout=10).json()
```
Não use `raise_for_status()` aqui
Ele transforma 402, 422 e 429 na mesma exceção, e as três pedem ações diferentes. O passo 4 trata uma por uma.
***
## Passo 3: Enviar, e guardar o código (4 min)
[Seção intitulada “Passo 3: Enviar, e guardar o código (4 min)”](#passo-3-enviar-e-guardar-o-código-4-min)
```python
resposta = send_message(
{
"from": os.environ["IPORTO_MAIL_FROM"],
"to": [pedido.cliente_email],
"subject": f"Seu pedido {pedido.numero}",
"html": f"Seu pedido {pedido.numero} foi confirmado.
",
"tags": ["transacional", f"pedido-{pedido.numero}"],
},
idempotency_key=f"pedido-{pedido.numero}",
)
if resposta.status_code == 202:
pedido.iporto_tracking_code = resposta.json()["message"]["tracking_code"]
pedido.save()
```
A resposta é **202**, não 200
202 quer dizer “aceita, e sai em seguida pela fila”. Código que compara com 200 nunca entra no ramo de sucesso.
A `Idempotency-Key` é o que torna a retentativa segura
Repetir a mesma requisição com a mesma chave devolve a mensagem original e o cabeçalho `Idempotent-Replayed: true` — nada é enviado de novo. Com corpo diferente e a mesma chave, a resposta é 422.
***
## Passo 4: Tratar a recusa (4 min)
[Seção intitulada “Passo 4: Tratar a recusa (4 min)”](#passo-4-tratar-a-recusa-4-min)
```python
corpo = resposta.json()
if resposta.status_code == 202:
pedido.iporto_tracking_code = corpo["message"]["tracking_code"]
pedido.save()
# Sem crédito: avise quem compra, não repita.
elif resposta.status_code == 402:
alertar_financeiro(corpo["error"])
# Corpo acima de 16 MB: mande o anexo por `url` em vez de base64.
elif resposta.status_code == 413:
logger.warning("[iPORTO] mensagem grande demais", extra={"pedido": pedido.id})
# Campo inválido. `errors` diz qual — não adivinhe.
elif resposta.status_code == 422:
logger.error("[iPORTO] recusa de validação", extra={"errors": corpo.get("errors")})
# Acima de 8.000 por minuto. `Retry-After` diz quantos segundos esperar.
elif resposta.status_code == 429:
espera = int(resposta.headers.get("Retry-After", 60))
reenviar_em(pedido, espera)
else:
logger.error("[iPORTO] falha inesperada", extra={"status": resposta.status_code})
```
Os códigos, com as distinções que mudam o seu código, estão em [Erros](/api/conceitos/erros/).
***
## Passo 5: Receber o evento de entrega (5 min)
[Seção intitulada “Passo 5: Receber o evento de entrega (5 min)”](#passo-5-receber-o-evento-de-entrega-5-min)
Configure o endereço no painel e exponha a rota. O corpo cru é necessário para conferir a assinatura:
```python
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.post("/webhooks/iporto")
def iporto_webhook():
# A verificação da assinatura está em /api/webhooks/verificar-assinatura/
# e usa request.get_data(), que é o corpo CRU.
evento = request.get_json(silent=True) or {}
codigo = evento.get("param", {}).get("message_tracking_code")
status = evento.get("param", {}).get("details", {}).get("delivery", {}).get("status")
atualizar_pedido_por_codigo(codigo, email_status=status)
return jsonify(ok=True)
```
Assine o corpo CRU, byte a byte
Serializar o JSON de novo muda um espaço ou a ordem das chaves, e a assinatura deixa de casar. Use `request.get_data()` para a conferência.
O mesmo objeto nos dois lugares
O que a consulta devolve é **idêntico** ao que o webhook entrega em `param.details` — o parser serve nos dois. Ver [Webhook e API](/api/conceitos/webhook-e-api/).
***
## Passo 6: SMS (opcional — 2 min)
[Seção intitulada “Passo 6: SMS (opcional — 2 min)”](#passo-6-sms-opcional--2-min)
```python
import re
send_message({
"channel": "sms",
"to": re.sub(r"\D", "", pedido.cliente_telefone),
"text": f"Seu pedido {pedido.numero} foi confirmado.",
})
```
O canal de SMS é liberado por conta
Sem a liberação, o envio é aceito e a mensagem não sai. Abra um chamado no portal do cliente, em **Suporte → Abrir Chamado**, antes de integrar o SMS.
***
## Passo 7: Testes (4 min)
[Seção intitulada “Passo 7: Testes (4 min)”](#passo-7-testes-4-min)
```python
import responses
@responses.activate
def test_guarda_o_codigo_de_rastreio():
responses.add(
responses.POST,
f"{BASE}/messages",
json={"message": {"tracking_code": "3f2a7c18-9d4e-4b6a-8c1f-5e2d7a0b3f49"}},
status=202,
)
resposta = send_message({"from": "x", "to": ["y@z.com.br"], "subject": "a", "html": "a
"})
assert resposta.status_code == 202
assert resposta.json()["message"]["tracking_code"]
```
**Checklist:**
* [ ] O envio devolve 202 e o código de rastreio fica gravado
* [ ] Repetir com a mesma `Idempotency-Key` devolve `Idempotent-Replayed: true`
* [ ] Um `from` que não é seu devolve 422 e `errors["from"]` aparece no log
* [ ] 429 reenfileira usando o `Retry-After`
* [ ] A rota de webhook responde 200 e atualiza o seu registro
***
Catálogo completo de campos e códigos: [Referência](/api/referencia/).
# Migrar o envio de e-mail de outro provedor
> Trocar SendGrid, Amazon SES, Resend, Postmark ou Mailgun pelo envio de e-mail da iPORTO — a equivalência de cada campo, o que muda na resposta e o que não tem equivalente.
Se o seu sistema já envia e-mail por um provedor, a troca é de **nomes de campo**: a forma do pedido é a mesma — um `POST` com JSON, autenticado por chave no cabeçalho.
Esta página é a tabela de equivalência. O caminho completo, com a conta de envio e o que fazer depois do envio, está em [Referência → Mensagens](/api/referencia/operations/tags/mensagens/).
## O formato, lado a lado
[Seção intitulada “O formato, lado a lado”](#o-formato-lado-a-lado)
| | |
| ------------ | --------------------------------------------------------- |
| Endereço | `POST https://api.iporto.com.br/api/external/v1/messages` |
| Autenticação | `Authorization: Bearer ` |
| Corpo | JSON |
| Resposta | **202** com a mensagem aceita |
O remetente: qualquer endereço do seu domínio
Como no Resend e no SES, basta o domínio estar cadastrado no painel do SMTP: qualquer endereço dele serve no `from` — `{seller}@seudominio.com.br` inclusive, sem cadastrar cada um. Duas diferenças:
* o domínio precisa de **ao menos uma conta de envio**: é ela que autentica a mensagem. Sem `from_auth`, autentica a conta do próprio `from`, quando ele é uma conta, ou a mais antiga do domínio; com `from_auth`, a que você escolher;
* **subdomínio é cadastrado como domínio próprio**: `mail.seudominio.com.br` não herda o cadastro de `seudominio.com.br`.
## Resend
[Seção intitulada “Resend”](#resend)
O mais parecido: os nomes quase coincidem.
| Resend | iPORTO | Nota |
| ------------------------- | ------------------------- | ------------------------------------------------ |
| `from` | `from` | igual, inclusive `Nome ` |
| `to` | `to` | **sempre lista** aqui, mesmo com um destinatário |
| `subject` | `subject` | igual |
| `html` · `text` | `html` · `text` | igual |
| `cc` · `bcc` · `reply_to` | `cc` · `bcc` · `reply_to` | **sempre listas** aqui |
| `headers` | `headers` | igual, objeto chave-valor |
| `attachments[].filename` | `attachments[].filename` | igual |
| `attachments[].content` | `attachments[].content` | base64 nos dois |
| `attachments[].path` | `attachments[].url` | só o nome muda |
| `tags[{name, value}]` | `tags[]` | aqui é **lista de texto**, sem par nome-valor |
| `scheduled_at` | — | não há agendamento |
| `id` da resposta | `message.tracking_code` | ver [A resposta](#a-resposta) |
**Antes:**
```json
{
"from": "Loja ",
"to": "destinatario@provedor.com.br",
"subject": "Seu pedido 1234",
"html": "Confirmado.
",
"tags": [{ "name": "tipo", "value": "transacional" }]
}
```
**Depois:**
```json
{
"from": "Loja ",
"to": ["destinatario@provedor.com.br"],
"subject": "Seu pedido 1234",
"html": "Confirmado.
",
"tags": ["tipo:transacional"]
}
```
Par nome-valor em `tags`
A convenção que funciona bem é juntar com dois-pontos, como acima: a etiqueta volta inteira na consulta e no webhook, e você separa no seu lado.
## SendGrid
[Seção intitulada “SendGrid”](#sendgrid)
A diferença grande é o `personalizations`: aqui o pedido é plano.
| SendGrid | iPORTO | Nota |
| ---------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `from.email` + `from.name` | `from` | um campo só: `Nome ` |
| `personalizations[0].to[].email` | `to` | lista de endereços, sem `personalizations` |
| `personalizations[0].cc` · `bcc` | `cc` · `bcc` | no nível de cima |
| `subject` | `subject` | igual |
| `content[{type: "text/html"}].value` | `html` | campo direto |
| `content[{type: "text/plain"}].value` | `text` | campo direto |
| `reply_to.email` | `reply_to` | lista |
| `headers` | `headers` | igual |
| `attachments[].content` · `filename` · `type` | `attachments[].content` · `filename` · `content_type` | `type` vira `content_type` |
| `categories[]` | `tags[]` | igual na prática |
| `custom_args` | `tags[]` | não há campo de metadado livre; o que precisa voltar vira etiqueta |
| `send_at` | — | não há agendamento |
| `template_id` + `dynamic_template_data` | — | não há template; monte o HTML no seu lado |
| `tracking_settings.open_tracking` · `click_tracking` | `tracking.opens` · `tracking.clicks` | booleanos; exigem o rastreamento do domínio verificado — ver [Medição de abertura e clique](#medi%C3%A7%C3%A3o-de-abertura-e-clique) |
| `X-Message-Id` do cabeçalho | `message.tracking_code` | ver [A resposta](#a-resposta) |
**Antes:**
```json
{
"personalizations": [{ "to": [{ "email": "destinatario@provedor.com.br" }] }],
"from": { "email": "pedidos@cliente.com.br", "name": "Loja" },
"subject": "Seu pedido 1234",
"content": [{ "type": "text/html", "value": "Confirmado.
" }],
"categories": ["transacional"]
}
```
**Depois:**
```json
{
"from": "Loja ",
"to": ["destinatario@provedor.com.br"],
"subject": "Seu pedido 1234",
"html": "Confirmado.
",
"tags": ["transacional"]
}
```
Um `personalizations` com vários destinatários não é um pedido aqui
No SendGrid, `personalizations` permite um envio com conteúdo diferente por destinatário. Aqui um pedido é **uma** mensagem: para dez conteúdos diferentes, são dez chamadas. Para a mesma mensagem a várias pessoas, use `to` com a lista.
## Amazon SES
[Seção intitulada “Amazon SES”](#amazon-ses)
| Amazon SES (API v2) | iPORTO | Nota |
| ------------------------------------------ | ----------------------- | -------------------------------------------- |
| `FromEmailAddress` | `from` | igual, aceita `Nome ` |
| `Destination.ToAddresses` | `to` | igual |
| `Destination.CcAddresses` · `BccAddresses` | `cc` · `bcc` | igual |
| `ReplyToAddresses` | `reply_to` | igual |
| `Content.Simple.Subject.Data` | `subject` | campo direto |
| `Content.Simple.Body.Html.Data` | `html` | campo direto |
| `Content.Simple.Body.Text.Data` | `text` | campo direto |
| `Content.Raw.Data` (MIME montado à mão) | `attachments[]` | **não é preciso montar MIME**: anexo é campo |
| `EmailTags[{Name, Value}]` | `tags[]` | lista de texto |
| `ConfigurationSetName` | — | não há conjunto de configuração |
| `MessageId` da resposta | `message.tracking_code` | ver [A resposta](#a-resposta) |
Anexo deixa de ser trabalho seu
No SES, mandar anexo exige trocar `Content.Simple` por `Content.Raw` e montar a mensagem MIME inteira em base64. Aqui `attachments` é uma lista de objetos, e o resto do pedido não muda.
**Antes:**
```json
{
"FromEmailAddress": "pedidos@cliente.com.br",
"Destination": { "ToAddresses": ["destinatario@provedor.com.br"] },
"Content": {
"Simple": {
"Subject": { "Data": "Seu pedido 1234" },
"Body": { "Html": { "Data": "Confirmado.
" } }
}
}
}
```
**Depois:**
```json
{
"from": "pedidos@cliente.com.br",
"to": ["destinatario@provedor.com.br"],
"subject": "Seu pedido 1234",
"html": "Confirmado.
"
}
```
## Postmark
[Seção intitulada “Postmark”](#postmark)
| Postmark | iPORTO | Nota |
| ------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `From` | `from` | igual |
| `To` (texto, separado por vírgula) | `to` | **lista**, não texto com vírgula |
| `Cc` · `Bcc` | `cc` · `bcc` | listas |
| `ReplyTo` | `reply_to` | lista |
| `Subject` | `subject` | igual |
| `HtmlBody` | `html` | só o nome muda |
| `TextBody` | `text` | só o nome muda |
| `Headers[{Name, Value}]` | `headers` | aqui é **objeto** chave-valor |
| `Attachments[{Name, Content, ContentType}]` | `attachments[{filename, content, content_type}]` | só os nomes mudam |
| `Tag` (uma só) | `tags[]` | aqui são até 10 |
| `Metadata` | `tags[]` | não há campo de metadado livre |
| `TrackOpens` · `TrackLinks` | `tracking.opens` · `tracking.clicks` | booleanos; o clique vale só para o HTML — ver [Medição de abertura e clique](#medi%C3%A7%C3%A3o-de-abertura-e-clique) |
| `MessageStream` | — | não há stream; a separação é por etiqueta |
| `MessageID` da resposta | `message.tracking_code` | ver [A resposta](#a-resposta) |
`ErrorCode: 0` não existe aqui
O Postmark responde **200** com `ErrorCode` no corpo, inclusive quando recusa. Aqui a recusa é o **código HTTP**: 402, 413, 422 ou 429, com o motivo no corpo. Se o seu código testa `ErrorCode`, ele passa a testar o status.
## Mailgun
[Seção intitulada “Mailgun”](#mailgun)
| Mailgun | iPORTO | Nota |
| -------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| corpo `multipart` ou `x-www-form-urlencoded` | **JSON** | é a mudança de forma |
| `from` | `from` | igual |
| `to` (repetido, ou com vírgula) | `to` | lista JSON |
| `cc` · `bcc` | `cc` · `bcc` | listas |
| `subject` | `subject` | igual |
| `html` · `text` | `html` · `text` | igual |
| `h:Reply-To` | `reply_to` | campo próprio |
| `h:X-Qualquer-Coisa` | `headers` | objeto, sem o prefixo `h:` |
| `attachment` (arquivo no multipart) | `attachments[]` | base64 em `content`, ou `url` |
| `o:tag` (repetido) | `tags[]` | lista |
| `v:minha-var` | `tags[]` | não há variável de usuário |
| `o:deliverytime` | — | não há agendamento |
| `o:tracking-opens` · `o:tracking-clicks` | `tracking.opens` · `tracking.clicks` | booleanos JSON; não há `o:tracking` geral — ver [Medição de abertura e clique](#medi%C3%A7%C3%A3o-de-abertura-e-clique) |
| `id` da resposta | `message.tracking_code` | ver [A resposta](#a-resposta) |
**Antes** (form-encoded):
```bash
curl -X POST https://api.mailgun.net/v3/cliente.com.br/messages \
-u "api:$MAILGUN_KEY" \
-F from="Loja " \
-F to=destinatario@provedor.com.br \
-F subject="Seu pedido 1234" \
-F html="Confirmado.
" \
-F o:tag=transacional
```
**Depois:**
```bash
curl -X POST https://api.iporto.com.br/api/external/v1/messages \
-H "Authorization: Bearer $IPORTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Loja ",
"to": ["destinatario@provedor.com.br"],
"subject": "Seu pedido 1234",
"html": "Confirmado.
",
"tags": ["transacional"]
}'
```
## A resposta
[Seção intitulada “A resposta”](#a-resposta)
Todo provedor devolve um identificador. Aqui ele se chama `message.tracking_code`, e é o que você guarda no lugar do `id`, do `MessageId` ou do `X-Message-Id`.
```json
{
"object": "message",
"channel": "email",
"message": { "tracking_code": "3f2a7c18-9d4e-4b6a-8c1f-5e2d7a0b3f49", "sent_at": null },
"delivery": { "status": "msg:yes:queue", "bounce": null }
}
```
Duas diferenças que mexem no seu código:
* **O status é 202, não 200.** A mensagem foi aceita e sai em seguida. Se o seu código compara com 200, passa a comparar com 202 — ou aceitar a faixa 2xx.
* **A resposta já tem a forma do estado da mensagem.** Os mesmos campos `delivery.status` e `delivery.bounce` que você vai ler depois na consulta já vêm aqui, no estado aceito. Não há um segundo formato para aprender.
## O webhook
[Seção intitulada “O webhook”](#o-webhook)
Se você usa webhook no provedor atual, a troca é de formato de evento, e o ganho é que **o corpo do evento é idêntico ao que a consulta devolve** — um parser serve para os dois.
Os eventos, o corpo de cada um e como verificar a assinatura estão em [Receber eventos](/api/webhooks/). A configuração é no painel, não por API.
## Medição de abertura e clique
[Seção intitulada “Medição de abertura e clique”](#medição-de-abertura-e-clique)
Desligada por padrão: sem o campo `tracking`, os seus links saem **intactos** e nenhum pixel é inserido. Para medir, peça no envio:
```json
"tracking": { "opens": true, "clicks": true }
```
* `clicks` troca cada link `http`/`https` no `href` de um link — ``, `` ou o botão VML do Outlook —, entre aspas duplas ou simples, no HTML por um endereço de redirecionamento no seu domínio de rastreio, e acrescenta `utm_source`, `utm_medium` e `utm_term` ao endereço final, antes do `#`;
* `opens` acrescenta uma imagem de rastreamento (o pixel) ao fim do HTML.
Cada abertura e cada clique chega pelo [webhook](/api/webhooks/eventos/), como `email.opened` e `email.clicked`.
Exige o rastreamento do domínio verificado
O domínio do `from` precisa do CNAME `track-s1` publicado e confirmado no painel do SMTP — ver [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/). Sem ele, o envio é aceito normalmente, os links saem como você escreveu e **nada é medido**. Se o seu relatório de abertura ficar zerado depois da troca, é a primeira coisa a conferir.
## O que não tem equivalente
[Seção intitulada “O que não tem equivalente”](#o-que-não-tem-equivalente)
Vale conferir antes de começar, porque é o que faz uma migração parar no meio:
| O que você usa hoje | Aqui |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Template no provedor**, com variáveis | Não existe. O HTML vai pronto no pedido — monte no seu lado, que é onde os dados estão |
| **Agendamento** (`send_at`, `scheduled_at`, `o:deliverytime`) | Não existe. O envio é imediato; agende no seu lado |
| **Conteúdo diferente por destinatário** numa chamada | Um pedido é uma mensagem. Para conteúdos diferentes, uma chamada cada |
| **Metadado livre** (`custom_args`, `Metadata`, `v:`) | Use `tags`, até 10 por mensagem |
## Testar antes de trocar
[Seção intitulada “Testar antes de trocar”](#testar-antes-de-trocar)
Mande um envio para um endereço seu e confira três coisas: a mensagem chegou, o remetente aparece como você espera, e a consulta pelo `tracking_code` responde. Depois disso, a troca no seu código é de nomes de campo.
O caminho completo está em [Referência → Mensagens](/api/referencia/operations/tags/mensagens/).
# Receber eventos por webhook
> Configurar um endereço do seu sistema para receber os eventos de cada mensagem — aceite, entrega, falha, abertura e clique.
O webhook avisa o seu sistema, na hora, o que aconteceu com cada mensagem: ela foi aceita, entregue, voltou, foi aberta, teve um link clicado. Em vez de consultar a API de tempo em tempo, o seu sistema recebe um `POST` a cada evento.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* Um endereço **público** do seu sistema para receber os eventos. Endereço de rede interna, `localhost` ou IP privado não é aceito: o envio sai dos nossos servidores e precisa alcançar o seu.
* **Use HTTPS.** Aceitamos `http://`, e nele o corpo do evento e o seu token de autorização trafegam em texto puro.
* Esse endereço precisa responder **2xx em até 15 segundos**. Se o seu processamento é demorado, responda primeiro e processe depois.
## Passo a passo
[Seção intitulada “Passo a passo”](#passo-a-passo)
O webhook é configurado **por serviço**, no painel de cada um — e a tela muda de nome:
| Serviço | Onde configurar |
| ------------- | ---------------------------------------------------------------------- |
| E-mail (SMTP) | **Webhook → Endpoints** |
| Prospecção | **Webhook → Endpoints** — é a mesma configuração do e-mail; ver abaixo |
| SMS | **Webhook → Endpoints** |
A Prospecção usa o webhook de e-mail — e isso é bom
As mensagens da Prospecção saem pelo mesmo servidor de e-mail, então os eventos delas são os do **canal e-mail**: entrega, falha, abertura e clique, com assinatura, cabeçalhos `X-iPORTO-*` e as seis tentativas descritas aqui.
**É uma configuração só para a conta.** O que você cadastrar no painel de Prospecção é o que aparece no painel de e-mail, e vice-versa — não são dois webhooks.
Para separar o que é da Prospecção, use `param.tags`: as mensagens dela chegam com `prospect` e `application_prospect_email` na lista. Ver [Os eventos e seus corpos](/api/webhooks/eventos/).
No painel de e-mail (SMTP):
1. Vá em **Webhook → Endpoints** e clique em **Novo endpoint**.
2. Em **URL do endpoint**, informe o endereço que vai receber os eventos.
3. Em **Domínios de envio**, deixe nenhum marcado para receber os eventos de todos os domínios da conta, ou marque os que este endereço deve receber — ver [Só os eventos de alguns domínios](#s%C3%B3-os-eventos-de-alguns-dom%C3%ADnios).
4. Em **Autorização**, escolha **Nenhuma** ou **Bearer Token**. Escolhendo Bearer Token, informe em **Token de autorização** o valor que o seu sistema espera receber no cabeçalho `Authorization`.
5. Marque os **eventos** que você quer receber — eles vêm todos marcados. Ver [Os eventos e seus corpos](/api/webhooks/eventos/).
6. Clique em **Criar**. O endereço novo recebe o formato **v2** do corpo — a tela avisa, e [a comparação com o formato anterior](/api/webhooks/formatos/) diz o que muda. Trocar para o v1 é um clique, depois de criar.
7. Na tela do endpoint, em **Segredo de assinatura**, clique em **Gerar segredo** e copie o valor. É com ele que o seu sistema confere que o envio veio da iPORTO — ver [Verificar a assinatura](/api/webhooks/verificar-assinatura/).
O segredo aparece uma única vez
Ele não é exibido em nenhuma leitura posterior. Se você fechar a tela sem copiá-lo, gere outro. O mesmo vale para o token de autorização: depois de salvo, a tela mostra apenas os últimos quatro caracteres.
Ao gerar um segredo novo, **o anterior continua válido por 24 horas**. Use essa janela para publicar o novo no seu sistema sem recusar os eventos que chegarem no meio.
No SMS o caminho é o mesmo, com dois eventos
O painel de SMS tem a mesma tela — **Webhook → Endpoints** —, com os até cinco endereços, o segredo de assinatura de cada um e o teste por evento. O canal tem dois eventos: entrega e rejeição.
Se você integrou o webhook de SMS antes de outubro de 2026, a tela que você conhece é **Gatilhos**: ela tinha um endereço só e não dava acesso ao segredo. A configuração que estava lá continua valendo — ela aparece em Endpoints como o endereço **principal** do canal.
## Mais de um endereço no mesmo canal
[Seção intitulada “Mais de um endereço no mesmo canal”](#mais-de-um-endereço-no-mesmo-canal)
Você cadastra até **cinco** endereços por canal — por exemplo, um para o ERP e outro para a ferramenta de atendimento. Todos os ativos que assinam o evento recebem o mesmo evento, cada um com o seu próprio `X-iPORTO-Delivery`.
Na tela de um endpoint, os controles ficam na coluna da direita:
| Ação | O que faz |
| ------------------------- | ----------------------------------------------------------------- |
| **Pausar** / **Reativar** | para de receber sem perder a configuração |
| **Tornar principal** | marca qual endereço representa o canal |
| **Gerar segredo** | gera o segredo de assinatura daquele endereço — cada um tem o seu |
| **Remover** | apaga o endereço |
Remover o principal promove outro
Quando o endereço principal é removido, o mais antigo que sobra assume — ativo antes de pausado. Você nunca fica sem um principal enquanto houver no canal um endereço sem restrição de domínio.
## Só os eventos de alguns domínios
[Seção intitulada “Só os eventos de alguns domínios”](#só-os-eventos-de-alguns-domínios)
Uma conta com vários domínios pode separar os eventos por sistema: um endereço para os envios de `loja.com.br`, outro para os de `cobranca.com.br`. O endereço restrito recebe apenas os eventos das mensagens enviadas pelos domínios marcados em **Domínios de envio** — na criação ou em **Editar**, na tela do endpoint.
| Situação | O que acontece |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nenhum domínio marcado | o endereço recebe de todos os domínios da conta, inclusive dos cadastrados depois — é assim que todo endereço criado antes desta opção funciona |
| Domínio removido da conta | continua na lista do endereço; sem envio novo por ele, chegam só os eventos das mensagens que já tinham saído — abertura, clique, bounce. Cadastrado de novo, volta a valer sem editar o endereço. A tela do endpoint avisa |
| **Tornar principal** | não vale para endereço restrito a domínios; para torná-lo principal, desmarque os domínios |
| Botão **Testar** | ignora a restrição — o evento de exemplo não vem de domínio nenhum |
O domínio que conta é o da **conta de envio que autenticou**, e não o do `From` que o destinatário vê. É o mesmo `smtp_domain_id` que chega no corpo do evento.
A opção existe só no canal **e-mail**: o SMS não tem domínio de envio.
## O que acontece depois
[Seção intitulada “O que acontece depois”](#o-que-acontece-depois)
A cada evento, a iPORTO faz uma requisição ao seu endereço:
```plaintext
POST https://seu-sistema.com.br/webhook
Content-Type: application/json
```
O seu sistema responde **2xx** e nada mais é necessário. Qualquer outra resposta, ou nenhuma resposta, é tratada como falha — ver [Repetição e falhas](/api/webhooks/repeticao-e-falhas/).
### Os cabeçalhos de cada envio
[Seção intitulada “Os cabeçalhos de cada envio”](#os-cabeçalhos-de-cada-envio)
| Cabeçalho | O que é |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | sempre `application/json` |
| `User-Agent` | `iPORTO-Webhook/2 (+https://docs.iporto.com.br/api/webhooks/)` — é por ele que você libera o envio em firewall ou WAF |
| `X-iPORTO-Event` | o nome do evento, igual ao campo `event` do corpo |
| `X-iPORTO-Event-Id` | identificador do **fato** |
| `X-iPORTO-Delivery` | identificador **desta entrega** |
| `X-iPORTO-Attempt` | número da tentativa, começando em `1` |
| `X-iPORTO-Timestamp` | instante do envio, ISO-8601 |
| `X-iPORTO-Signature` | a assinatura; ver [Verificar a assinatura](/api/webhooks/verificar-assinatura/) |
| `Authorization` | `Bearer `, quando você configurou um |
### Os dois identificadores, e para que serve cada um
[Seção intitulada “Os dois identificadores, e para que serve cada um”](#os-dois-identificadores-e-para-que-serve-cada-um)
* **`X-iPORTO-Event-Id`** é o fato. Se você cadastrou mais de um endereço no canal, todos recebem o mesmo `Event-Id` para o mesmo acontecimento — é com ele que você sabe que recebeu o mesmo evento duas vezes, e não dois eventos.
* **`X-iPORTO-Delivery`** é esta entrega: o evento mais o endereço de destino. É o valor a guardar para **descartar repetição**: uma retentativa chega com o mesmo `Delivery` e com `Attempt` maior.
Guarde o `X-iPORTO-Delivery` e ignore o que já processou
Uma entrega pode chegar mais de uma vez. Uma resposta sua que demorou mais de 15 segundos é tratada como falha aqui e será repetida, mesmo que você já a tenha processado.
## Casar o evento com a sua mensagem
[Seção intitulada “Casar o evento com a sua mensagem”](#casar-o-evento-com-a-sua-mensagem)
Todo corpo traz `param.message_tracking_code`: é o localizador da mensagem, e é o campo para guardar do seu lado.
O código é gerado por nós e volta na resposta do envio, em `message.tracking_code`. **Não é possível escolhê-lo**: o cabeçalho `X-Request-Id` na requisição de envio é ignorado. Para carimbar um identificador seu — o número do pedido, por exemplo —, use `tags`, que voltam em todo evento em `param.tags`.
⚠️ **Na porta de envio anterior a resposta ainda ecoa o `X-Request-Id` que você mandou**, no cabeçalho — mas o código de rastreio é o de `data.message_tracking_code`, e é ele que chega nos eventos.
O código também vai no cabeçalho `X-Mailer-Tracking-Code` **da mensagem enviada**, e as etiquetas, no `X-Mailer-Tags`.
Esses cabeçalhos chegam ao destinatário
Como qualquer cabeçalho de e-mail, eles aparecem para quem usar “ver código-fonte” na caixa de entrada. Não ponha em `tags` nada que você não queira mostrar — número de contrato interno, identificador de cliente de terceiro, dado pessoal.
Os campos `param.message_id` e `param.message_id_relay` **não** correspondem ao que a API devolve no envio: são identificadores gerados pelo servidor de envio e pelo relay no momento da transmissão, e só existem a partir dali. Servem para rastreamento junto ao suporte, não como chave de correlação.
## O corpo traz o registro inteiro da mensagem
[Seção intitulada “O corpo traz o registro inteiro da mensagem”](#o-corpo-traz-o-registro-inteiro-da-mensagem)
Além do localizador, todo evento traz **`param.details`**: assunto, remetente, destinatários, etiquetas, o desfecho da entrega e — quando houve falha — a resposta do servidor de destino, com o código e a frase. É o mesmo que você vê no painel, e está ali para você não precisar consultar a API depois de cada evento.
Em abertura e clique ele traz também o acesso do destinatário: IP, navegador e plataforma.
Os campos estão descritos em [O bloco `param.details`](/api/webhooks/eventos/#o-bloco-paramdetails).
Quem já integrou não precisa fazer nada
`details` é um campo novo **dentro de `param`**. Nenhum campo anterior mudou de nome, de valor ou de posição, e o topo do corpo continua com as mesmas quatro chaves.
## Testar
[Seção intitulada “Testar”](#testar)
Na tela de um endpoint, cada evento marcado tem o botão **Testar**: ele dispara aquele evento para **aquele endereço** — e só para ele, mesmo que você tenha outros no canal. É o caminho para homologar o seu handler sem esperar por uma mensagem de verdade.
**O caminho é o real; os dados são de exemplo.** O teste sai com os mesmos cabeçalhos, a mesma assinatura, o formato do endpoint (v1 ou v2) e as mesmas tentativas de um evento de produção, e aparece no **Histórico de Disparos**. A mensagem é que não existe:
| Campo | Valor no teste |
| ------------------ | ------------------------------------------------------------------------------------------ |
| Código de rastreio | sempre `9f8b3c2e-7d41-4a6f-9b2c-1e5d8a0f3b47` — use-o para descartar testes no seu sistema |
| Destinatário | `destinatario@exemplo.com.br`, ou `5511999998888` no SMS |
| `param.id` | novo a cada clique, para o segundo teste não ser descartado como repetição do primeiro |
Um teste **abandonado** — sem resposta 2xx depois de todas as tentativas — conta para a [desativação por falhas](/api/webhooks/repeticao-e-falhas/#quando-o-endere%C3%A7o-%C3%A9-desativado), como qualquer outro envio.
Teste os eventos um por um, não só um deles
Os corpos têm **três formas** — entrega e falha, aceite pela API, e engajamento — e elas diferem no que importa: `email` deixa de ser lista, os contadores de `about` mudam, e no clique aparece `param.link`. Quem homologa contra um evento só descobre a diferença no primeiro bounce em produção. Ver [Os eventos e seus corpos](/api/webhooks/eventos/).
O evento precisa estar **marcado** no endpoint, e o endpoint precisa estar **ativo**: fora disso a tela recusa o teste e diz por quê, em vez de dizer “enviado” sobre um POST que não houve.
No painel de **SMS** é igual: cada evento marcado tem o seu botão **Testar**, na tela do endpoint.
E em **Webhook → Histórico de Disparos** o detalhe de cada disparo tem o botão **Reenviar**, que repete o envio para o endereço configurado hoje — útil para conferir uma correção no seu endpoint sem precisar de uma mensagem nova.
## Limites
[Seção intitulada “Limites”](#limites)
| | |
| --------------------------- | ------------------------------------------------------------------ |
| timeout de cada tentativa | 15 segundos |
| tentativas | 6 — a última cerca de **10 horas e 36 minutos** depois da primeira |
| esperas entre as tentativas | 1, 5 e 30 minutos, 2 horas e 8 horas |
| histórico de disparos | 7 dias |
| redirecionamento | não seguimos |
| endereços por canal | até 5 |
As esperas estão detalhadas em [Repetição e falhas](/api/webhooks/repeticao-e-falhas/).
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A tela recusa o endereço informado | Endereço de rede interna, `localhost`, IP privado ou esquema diferente de `http`/`https` | Use um endereço público, alcançável da internet |
| Nenhum evento chega | Nenhum evento marcado na tela, ou endereço salvo vazio | Confira as caixas de evento e salve de novo; use o botão de enviar evento de teste para confirmar o caminho |
| Os eventos pararam de chegar, e você recebeu um e-mail de aviso | Dez entregas seguidas sem resposta 2xx desativaram o endereço | Corrija o que impedia a resposta e clique em **Reativar endpoint** na tela do endpoint |
| O mesmo evento chega mais de uma vez | Sua resposta passou de 15 segundos, ou não foi 2xx | Responda 2xx antes de processar, e descarte repetição pelo `X-iPORTO-Delivery` |
| A assinatura não confere | O corpo foi interpretado e serializado de novo antes de assinar, ou só um valor `v1` foi lido | Assine o corpo cru e trate `v1` como lista — ver [Verificar a assinatura](/api/webhooks/verificar-assinatura/) |
| Chega evento de uma mensagem que você não reconhece | O endereço está configurado na conta, e a conta pode ter mais de um sistema enviando | Restrinja o endereço aos domínios do seu sistema em **Domínios de envio**, use `param.message_tracking_code` para resolver a mensagem, e `tags` no envio para carimbar o seu próprio identificador |
| Um endereço restrito a domínios parou de receber | O domínio foi removido da conta, e não há envio novo por ele | Cadastre o domínio de novo, ou troque os domínios do endereço em **Editar** |
# Os eventos de webhook e seus corpos
> A lista de eventos por canal, o que cada um significa e o corpo JSON que chega ao seu endereço.
Cada evento marcado na tela do endpoint gera um `POST` para o seu endereço. Esta página lista os eventos de cada canal e o corpo que chega em cada um.
O nome do evento vem no campo `event` do corpo e também no cabeçalho `X-iPORTO-Event`.
## Canal e-mail
[Seção intitulada “Canal e-mail”](#canal-e-mail)
| Evento | Como aparece na tela | Quando acontece |
| --------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `msg_deliverability_yes_queue` | Mensagem recebida | a mensagem foi aceita — **somente no envio pela API**; o envio por SMTP não gera este evento |
| `msg_deliverability_yes_delivery` | Mensagem entregue ao destinatário | a mensagem foi entregue ao servidor do destinatário |
| `msg_deliverability_not_delivery_soft_bounce` | Falha temporária na entrega | recusa temporária do provedor; a entrega ainda pode acontecer |
| `msg_deliverability_not_delivery_hard_bounce` | Falha permanente na entrega | recusa definitiva, normalmente endereço inexistente |
| `msg_deliverability_not_accepted` | Mensagem rejeitada (total ou parcial) | a mensagem foi descartada por filtro do destino — ou, no envio pela API, não saiu da plataforma (ver [Recusa antes de sair](#recusa-antes-de-sair--envio-pela-api)) |
| `msg_engagement_open` | E-mail foi aberto pelo destinatário | o destinatário abriu a mensagem — **somente no envio pela API que pede rastreio de abertura**; ver [Abertura e clique dependem do rastreio](#abertura-e-clique-dependem-do-rastreio) |
| `msg_engagement_click` | Link do e-mail foi clicado | o destinatário clicou em um link — **somente no envio pela API que pede rastreio de clique** |
| `msg_engagement_compliance_spam` | E-mail foi marcado como spam | o destinatário marcou a mensagem como spam e o provedor nos avisou |
### Abertura e clique dependem do rastreio
[Seção intitulada “Abertura e clique dependem do rastreio”](#abertura-e-clique-dependem-do-rastreio)
Marcar o evento no endpoint não basta: a abertura e o clique só existem quando o **envio** pede rastreio.
* No `POST /messages`, o campo `tracking` vem desligado por padrão. Para medir, envie `"tracking": { "opens": true, "clicks": true }` — só o que você quiser medir. Sem ele, o HTML chega ao destinatário como você mandou, e nada é medido. Na rota anterior de envio, o pedido é o `tracking_settings`.
* O domínio do remetente precisa do rastreamento verificado — o CNAME `track-s1`, em [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/).
* O envio por SMTP não é medido: o HTML passa pelo servidor sem alteração.
Quando os dois chegam
Sempre depois de `msg_deliverability_yes_delivery`, nunca antes. O evento sai depois de a mensagem ser arquivada, o que leva cerca de um a dois minutos depois do envio. Uma abertura feita antes disso espera até cerca de 5 minutos para ser enviada; feita depois, sai em segundos. Se o arquivamento atrasar, a espera seguinte é maior.
A reclamação de spam depende do provedor
`msg_engagement_compliance_spam` chega pelo canal de retorno (feedback loop) dos provedores que o oferecem — não é todo provedor, e não é toda reclamação. No mesmo momento em que o aviso é processado, o endereço do destinatário entra na [lista de supressão](/ajuda/smtp/lista-de-supressao/) do domínio, e o SMTP para de enviar para ele. O evento existe para você refletir isso no seu cadastro.
### Quais provedores avisam
[Seção intitulada “Quais provedores avisam”](#quais-provedores-avisam)
Nos últimos 12 meses, chegaram avisos de reclamação destes provedores:
| Provedor | Domínios mais comuns |
| ------------------------- | -------------------------------------------------------------------- |
| UOL | `uol.com.br`, `bol.com.br` |
| Microsoft (programa JMRP) | `hotmail.com`, `outlook.com`, `live.com` |
| Rede SPFBL | provedores menores e servidores de e-mail corporativo |
| Programa da Validity | Terra, Locaweb, Rackspace, OpenSRS, Italia Online, Fastmail, Synacor |
**Gmail e Yahoo não geram o evento.** O Gmail não envia aviso por mensagem, e do Yahoo não recebemos esses relatórios. Ausência do evento, nesses provedores, não quer dizer ausência de reclamação.
**O evento não é imediato.** Os avisos são processados uma vez por dia: o evento pode chegar até um dia depois da reclamação, somado ao tempo que o próprio provedor leva para avisar.
Entregue não é “na caixa de entrada”
`msg_deliverability_yes_delivery` significa que o servidor do destinatário **aceitou** a mensagem. O que acontece depois disso — caixa de entrada, promoções, spam — é decisão do provedor, e não há evento que a reporte.
## Canal SMS
[Seção intitulada “Canal SMS”](#canal-sms)
| Evento | Quando acontece |
| --------------------------------- | ----------------------------------- |
| `msg_deliverability_yes_delivery` | o SMS foi **aceito pela operadora** |
| `msg_deliverability_not_accepted` | o SMS não foi aceito |
No SMS, `yes_delivery` é “aceito pela operadora”
Não é a confirmação de entrega no aparelho. Se o seu relatório depende de entrega confirmada no aparelho, este não é o campo.
## Todo evento da tela é enviado
[Seção intitulada “Todo evento da tela é enviado”](#todo-evento-da-tela-é-enviado)
Não há, hoje, nenhuma caixa que você possa marcar e que não gere envio. **Tudo o que a tela oferece chega ao seu endereço** — desde que o fato aconteça: abertura e clique só existem quando o envio pede rastreio (ver [Abertura e clique dependem do rastreio](#abertura-e-clique-dependem-do-rastreio)).
Se você integrou o SMS antes de outubro de 2026, a tela antiga oferecia quatro caixas que nunca enviaram nada — resposta, descadastro, reclamação de spam e o aceite pela operadora. Elas saíram. Se o seu sistema esperava por algum desses eventos, ele nunca os recebeu, e não é defeito da sua integração.
Entrega confirmada no aparelho ainda não tem evento
No SMS, `msg_deliverability_yes_delivery` é “aceito pela operadora”. A confirmação de entrega no aparelho existe do nosso lado e **ainda não tem evento de webhook** — quando tiver, ele aparece na tabela acima, e esta nota sai.
A **Prospecção** não tem eventos próprios: as mensagens dela saem por e-mail e geram os eventos do canal e-mail, listados acima. Para separá-las das transacionais, olhe `param.tags` — elas chegam com `application_prospect_email`, `prospect` e `approach`.
## Os corpos
[Seção intitulada “Os corpos”](#os-corpos)
São quatro formas, pela origem do evento. Os campos não listados aqui podem aparecer e **não devem ser usados**: o que esta página descreve é o que tem contrato.
Em todas as formas, `param` traz também o **`details`** — o registro inteiro da mensagem, com assunto, remetente, destinatários, desfecho da entrega e o motivo da falha. Ele está descrito em [O bloco `param.details`](#o-bloco-paramdetails) e aparece inteiro nos dois primeiros exemplos abaixo.
### Mensagem processada — entrega, falha e descarte
[Seção intitulada “Mensagem processada — entrega, falha e descarte”](#mensagem-processada--entrega-falha-e-descarte)
```json
{
"email": [
"destinatario@provedor.com.br"
],
"event": "msg_deliverability_yes_delivery",
"about": {
"status": "msg:yes:finished",
"sum_hard_bounce": 0,
"sum_soft_bounce": 0,
"sum_discarded": 0
},
"param": {
"message_id": "1s9KpQ-0004Zx-2H",
"message_id_relay": "1s9KpR-0007Bd-9K",
"message_tracking_code": "",
"tags": [
"transacional",
"pedido-1234"
],
"details": {
"object": "message",
"event": {
"type": "email.delivered",
"occurred_at": "2026-10-15T09:12:04-03:00",
"emitted_at": "2026-10-15T09:14:31-03:00",
"id": "01M4YQV7RC6VKAVJM5E6B4TCY8"
},
"channel": "email",
"message": {
"tracking_code": "",
"message_id": "1s9KpQ-0004Zx-2H",
"message_id_relay": "1s9KpR-0007Bd-9K",
"subject": "Seu pedido 1234",
"body": null,
"from": "pedidos@cliente.com.br",
"from_visible": "Loja ",
"to": "destinatario@provedor.com.br",
"recipients": [
"destinatario@provedor.com.br"
],
"tags": [
"transacional",
"pedido-1234"
],
"smtp_domain_id": 4180,
"smtp_account_id": 9271,
"plan_type": "smtp",
"sent_at": "2026-10-15T09:11:58-03:00",
"id": ""
},
"delivery": {
"status": "msg:yes:finished",
"hard_bounce": 0,
"soft_bounce": 0,
"discarded": 0,
"trap": 0,
"bounce": null
},
"engagement": null
},
"id": ""
}
}
```
`about.status` e os contadores dizem o desfecho: `sum_hard_bounce` em 1 na falha permanente, `sum_soft_bounce` na temporária, `sum_discarded` no descarte por filtro.
### Aceite pela API
[Seção intitulada “Aceite pela API”](#aceite-pela-api)
```json
{
"email": "destinatario@provedor.com.br",
"event": "msg_deliverability_yes_queue",
"about": {
"status": "msg:yes:queue"
},
"param": {
"message_tracking_code": "",
"http_request_params": {
"address_to": "destinatario@provedor.com.br",
"subject": "Seu pedido 1234",
"html_body": "corpo"
},
"id": ""
}
}
```
Este corpo repete a sua requisição de envio
`param.http_request_params` traz a requisição que você fez, **incluindo o corpo da mensagem**. Se o seu endpoint grava o que recebe, ele passa a guardar o conteúdo dos seus e-mails. Vale decidir isso de propósito, não por acidente.
O `param.details` vem aqui também — foi omitido acima para não repetir o bloco. Neste evento a mensagem acabou de ser aceita e ainda não saiu, então `details.message.message_id` e `sent_at` vêm vazios. Pelo `POST /messages`, `subject`, `from` e `tags` já vêm preenchidos; pela porta de envio anterior, vêm vazios também — o que você enviou está em `param.http_request_params`, no mesmo corpo.
### Recusa antes de sair — envio pela API
[Seção intitulada “Recusa antes de sair — envio pela API”](#recusa-antes-de-sair--envio-pela-api)
No envio pela API, `msg_deliverability_not_accepted` também avisa que a mensagem **não saiu da plataforma**: o nosso servidor de envio recusou a credencial, devolveu erro definitivo, ou as tentativas por erro temporário se esgotaram, a mensagem venceu o prazo na fila, ou houve falha nossa. Na porta de envio anterior, sai também quando o `from` ou o `to` é inválido. A falha não é do destino: nenhum destinatário recebeu.
O corpo é mais curto que o da mensagem processada:
| Campo | O que traz |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | **lista** com todos os destinatários — no aceite é texto, com um só |
| `about.status` | `msg:not:undelivered` — ou `msg:not:undelivered:trashed`, quando a mensagem venceu o prazo na fila |
| `about.sum_hard_bounce` · `sum_soft_bounce` | `1` em `sum_hard_bounce` quando o erro foi definitivo, em `sum_soft_bounce` quando foi temporário ou de conexão; os dois `0` quando a causa é a credencial, o remetente ou o destinatário. `sum_discarded` é sempre `0` |
| `param.id` · `message_tracking_code` · `tags` | como nos outros eventos |
| `param.details` | o registro inteiro. `details.delivery.bounce` traz o código e a frase quando foi um servidor que recusou; é nulo quando a causa foi a credencial, o remetente, o destinatário, o prazo ou uma falha nossa |
### Engajamento — abertura e clique
[Seção intitulada “Engajamento — abertura e clique”](#engajamento--abertura-e-clique)
```json
{
"email": null,
"event": "msg_engagement_click",
"about": {
"status": "msg:yes:finished",
"sum_hard_bounce": null,
"sum_soft_bounce": null,
"sum_discarded": null
},
"param": {
"message_id": "1s9KpQ-0004Zx-2H",
"message_id_relay": "1s9KpR-0007Bd-9K",
"message_tracking_code": "",
"tags": [
"transacional",
"pedido-1234"
],
"link": "https://cliente.com.br/pedido/1234",
"details": {
"object": "message",
"event": {
"type": "email.clicked",
"occurred_at": "2026-10-15T14:02:17-03:00",
"emitted_at": "2026-10-15T14:02:17-03:00",
"id": "01M4Z8F3QW1ABCDEF2GHJK3MNP"
},
"channel": "email",
"message": {
"tracking_code": "",
"message_id": "1s9KpQ-0004Zx-2H",
"message_id_relay": "1s9KpR-0007Bd-9K",
"subject": "Seu pedido 1234",
"body": null,
"from": "pedidos@cliente.com.br",
"from_visible": "Loja ",
"to": "destinatario@provedor.com.br",
"recipients": [
"destinatario@provedor.com.br"
],
"tags": [
"transacional",
"pedido-1234"
],
"smtp_domain_id": 4180,
"smtp_account_id": 9271,
"plan_type": "smtp",
"sent_at": "2026-10-15T09:11:58-03:00",
"id": ""
},
"delivery": {
"status": "msg:yes:finished",
"hard_bounce": 0,
"soft_bounce": 0,
"discarded": 0,
"trap": 0,
"bounce": null
},
"engagement": {
"link": "https://cliente.com.br/pedido/1234",
"ip": "203.0.113.7",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
"device": "desktop",
"platform": "macOS",
"referer": null
}
},
"id": ""
}
}
```
No clique, `param.link` traz o endereço clicado. Na abertura, o campo não existe.
É só aqui que `details.engagement` deixa de ser nulo: ele descreve o acesso do destinatário, e nos eventos de entrega ninguém acessou nada.
`email` vem nulo no engajamento
E os contadores de `about` também. É assim desde a primeira versão e não vai mudar: o seu código não deve depender da presença desses campos — use `message_tracking_code` para resolver a mensagem.
### Canal SMS
[Seção intitulada “Canal SMS”](#canal-sms-1)
```json
{
"phone": "5511999998888",
"event": "msg_deliverability_yes_delivery",
"about": "",
"param": {
"id": ""
}
}
```
No SMS, `about` é uma string vazia
Não um objeto, como no e-mail. Quem escreve um tratamento único para os dois canais precisa saber disso.
O `param.details` vem aqui também, com `channel: "sms"`. O que o canal não tem fica nulo: `subject`, `message_id_relay`, `tags` e o bloco `engagement`. Em `from` e `to` vão os telefones.
## O bloco `param.details`
[Seção intitulada “O bloco param.details”](#o-bloco-paramdetails)
É o registro inteiro da mensagem, o mesmo que você vê no painel — assunto, remetente, destinatários, desfecho da entrega e, quando houve falha, a resposta do servidor de destino. Ele existe para você não precisar consultar a API depois de cada evento.
Está em **todo** evento, nos dois canais, nas três formas de corpo.
É acréscimo, e nada mais
Nenhuma chave anterior mudou de nome, de valor ou de posição, e o topo do corpo segue com as mesmas quatro chaves. Quem já integrou não precisa fazer nada: quem lê `param.message_id` hoje continua lendo.
| Bloco | O que traz |
| ------------ | ------------------------------------------------------------- |
| `object` | sempre `"message"` |
| `event` | o fato: tipo, quando ocorreu, quando saiu, e o identificador |
| `channel` | `email` ou `sms` |
| `message` | a mensagem: assunto, remetente, destinatários, etiquetas |
| `delivery` | o desfecho da entrega, com o motivo da falha |
| `engagement` | o acesso do destinatário — **nulo** fora de abertura e clique |
### `event`
[Seção intitulada “event”](#event)
| Campo | O que é |
| ------------- | ------------------------------------------------------------------------------------- |
| `type` | o nome do evento no formato novo — `email.delivered`, `email.clicked`, `sms.accepted` |
| `occurred_at` | quando o fato aconteceu |
| `emitted_at` | quando nós o emitimos |
| `id` | identificador do fato; é o mesmo valor do cabeçalho `X-iPORTO-Event-Id` |
Os dois instantes respondem “por que o webhook demorou”
`occurred_at` é quando o provedor respondeu; `emitted_at` é quando o evento saiu daqui. A diferença entre os dois é o nosso tempo de processamento, e ela é visível — em vez de você precisar inferi-la do horário em que o `POST` chegou.
`event.type` e o campo `event` do corpo são nomenclaturas diferentes
`event.type` usa os nomes do formato novo (`email.delivered`); o campo `event`, no topo do corpo, usa os desta versão (`msg_deliverability_yes_delivery`). Os dois descrevem o mesmo fato. **Para decidir o que fazer, use o `event` do topo** — é ele que tem contrato aqui.
### `message`
[Seção intitulada “message”](#message)
| Campo | O que é |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `tracking_code` | o localizador da mensagem — o mesmo de `param.message_tracking_code` |
| `message_id` | identificador do servidor de envio |
| `message_id_relay` | identificador do relay |
| `subject` | o assunto |
| `body` | o texto da mensagem — **só em SMS recebido**; em e-mail é sempre nulo |
| `from` | o endereço remetente |
| `from_visible` | o remetente como o destinatário o vê, com nome |
| `to` | o destinatário principal |
| `recipients` | todos os destinatários, como lista |
| `tags` | as suas etiquetas, as mesmas de `param.tags` |
| `smtp_domain_id` | o domínio de envio |
| `smtp_account_id` | a conta de autenticação usada |
| `plan_type` | de onde a mensagem saiu — `smtp`, `email_marketing`, `marketing` ou `prospect` |
| `attachments_dropped` | anexos por URL que **não** foram obtidos, e a mensagem saiu sem eles: `[{ filename, reason }]`. Lista vazia quando nada faltou |
| `sent_at` | quando a mensagem saiu |
| `id` | identificador do registro de histórico; o mesmo de `param.id` |
### `delivery`
[Seção intitulada “delivery”](#delivery)
| Campo | O que é |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | o status — na mensagem processada, `msg:yes:finished` com sufixo quando houve falha (`:with:bounce`, `:with:filter`, `:with:trap`); no aceite, `msg:yes:queue`; na recusa antes de sair, `msg:not:undelivered` ou `msg:not:undelivered:trashed` |
| `hard_bounce` | quantos destinatários deram falha permanente |
| `soft_bounce` | quantos deram falha temporária |
| `discarded` | quantos o destino descartou ou filtrou |
| `trap` | quantos caíram em armadilha de spam |
| `bounce` | o motivo, quando houve |
| `recipients` | o resultado de **cada** destinatário — `email`, `domain`, `kind`, `code`, `answer`, `discard_reason`. `kind` é `null` (entregue), `hard`, `soft`, `discarded`, `trap` ou `unknown` (o registro não permite classificar); `code`/`answer` vêm sempre que a frase é do servidor de destino, e `discard_reason` só quando fomos nós que descartamos. Lista vazia antes do arquivamento |
`delivery.bounce` é o campo que mais muda o seu atendimento: ele diz **qual foi a resposta do servidor de destino**, e não só que houve uma falha.
```json
{
"kind": "hard",
"code": "550",
"answer": "550 5.1.1 The email account does not exist",
"domain": "exemplo.com.br"
}
```
| Campo | O que é |
| -------- | ------------------------------------------------ |
| `kind` | `hard`, `soft`, `discarded` ou `trap` |
| `code` | o código SMTP extraído da resposta |
| `answer` | a resposta do servidor de destino, como ela veio |
| `domain` | o domínio que respondeu |
`bounce` pode vir nulo mesmo em evento de falha
Ele vem nulo quando não houve falha e também quando o detalhe da mensagem não estava disponível no momento de emitir o evento — o campo é um extra, e não vale uma consulta a mais no caminho de cada evento. **Não construa a sua lógica sobre a presença dele**: o desfecho está em `about` e em `delivery`.
### `engagement`
[Seção intitulada “engagement”](#engagement)
Só em abertura e clique. Nos outros eventos é `null`.
| Campo | O que é |
| ------------ | ------------------------------------------------ |
| `link` | o endereço clicado; nulo na abertura |
| `ip` | o IP do acesso |
| `user_agent` | o `User-Agent` recebido |
| `device` | o tipo de dispositivo |
| `platform` | o sistema operacional |
| `referer` | a origem do clique, quando o navegador a informa |
Este bloco é dado pessoal do seu destinatário
IP e `User-Agent` identificam uma pessoa, e quem recebe passa a ser responsável por eles. Se o seu sistema não precisa desses campos, descarte-os na entrada em vez de gravá-los por acidente.
O corpo ficou maior
Com `details`, um evento sai de cerca de 400 bytes para cerca de 1,5 KB. Se o seu endpoint tem limite de tamanho de corpo, ele precisa de folga. O prazo de resposta continua o mesmo: 15 segundos.
## As etiquetas
[Seção intitulada “As etiquetas”](#as-etiquetas)
O campo `param.tags` traz as etiquetas que você enviou na requisição de envio, no campo `tags`. Elas viajam com a mensagem e voltam em todo evento dela — é o caminho para carregar a sua própria classificação (campanha, tipo de mensagem, identificador de pedido) sem depender de uma consulta do seu lado.
A iPORTO também acrescenta as suas. Mensagem enviada pela **Prospecção** chega com `application_prospect_email`, `prospect` e `approach`, e é assim que você separa o que é prospecção do que é transacional sem precisar de outro endereço de webhook.
## O formato não muda, e você não fica para trás
[Seção intitulada “O formato não muda, e você não fica para trás”](#o-formato-não-muda-e-você-não-fica-para-trás)
**Nenhum campo descrito aqui vai desaparecer, mudar de nome ou mudar de posição.** É o compromisso desta versão do formato, e ele vale sem prazo: não há data de fim de vida.
Um formato novo, quando houver, será **opcional e escolhido por endereço** — e você não precisa fazer nada para continuar funcionando.
E o formato atual continua recebendo melhoria de **dado**:
| | |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| campo novo dentro de `param.details` | **você recebe**, sem mexer em nada |
| tipo de evento novo | só no formato novo — o atual nomeia os eventos pelos nomes desta página, e um evento novo não tem nome aqui |
| mudança no significado de um evento que já existe | **nunca** nesta versão: seria quebrar quem já conta em cima dele |
Programe tolerando campo novo
A única coisa que pedimos do seu lado: **não recuse o corpo por conter chave que você não conhece.** Validação estrita de `param` já quebraria hoje ao trocar de evento — `link` só aparece no clique, `http_request_params` só no aceite pela API —, e é ela que transforma uma melhoria nossa em incidente seu.
# Os dois formatos de corpo — v1 e v2
> O formato novo tem envelope plano, nomes de evento claros e eventos que o atual não tem. É opcional, escolhido por endereço, e não mexe em quem já integrou.
Os eventos podem chegar em dois formatos de corpo, e a escolha é **por endereço**:
| | v1 | v2 |
| -------------------- | ------------------------------------------ | -------------------------------------------------- |
| quem usa | quem integrou até outubro de 2026 | **endereços novos**, e quem trocar |
| o corpo | `email`/`phone`, `event`, `about`, `param` | `id`, `event`, `api_version`, `created_at`, `data` |
| nome do evento | `msg_deliverability_yes_delivery` | `email.delivered` |
| os dados da mensagem | em `param.details` | em `data` — **é o mesmo objeto** |
| exige https | não | **sim** |
Você não precisa fazer nada
O v1 continua existindo, sem prazo de validade, e **nenhum campo dele vai desaparecer ou mudar de nome**. Se você já integrou e está satisfeito, não há migração a fazer: o formato de um endereço só muda quando alguém clica para trocar.
Endereço NOVO nasce em v2
Desde outubro de 2026, um endpoint cadastrado agora recebe o formato v2. Os endereços que já existiam continuam exatamente como estavam.
Se você vai cadastrar um segundo endereço para um sistema que já trata o formato antigo, **troque para v1 depois de criar** — é um clique na tela do endpoint, e a tela de criação avisa qual formato ele vai receber.
## O que o v2 resolve
[Seção intitulada “O que o v2 resolve”](#o-que-o-v2-resolve)
**Um lugar só para os dados.** No v1 eles estão espalhados por três chaves com história própria: `email` é lista num evento, string noutro e nula no engajamento; `about` é objeto no e-mail e string vazia no SMS; `param` muda por evento. No v2 tudo está em `data`.
**Nome de evento que diz o que aconteceu.** `email.delivered` em vez de `msg_deliverability_yes_delivery` — e, mais importante, com o significado certo (abaixo).
**Eventos que o v1 não tem**, hoje três, todos de SMS.
Se você já lê o `param.details` do v1, metade do trabalho está feita
O `data` do v2 é **o mesmo objeto** que o v1 entrega em `param.details`. Quem já trata um trata o outro; o que muda é o envelope em volta.
## O corpo v2
[Seção intitulada “O corpo v2”](#o-corpo-v2)
```json
{
"event": "email.bounced.hard",
"api_version": "2026-10-15",
"created_at": "2026-10-15T09:14:31-03:00",
"data": {
"object": "message",
"event": {
"type": "email.bounced.hard",
"occurred_at": "2026-10-15T09:12:04-03:00",
"emitted_at": "2026-10-15T09:14:31-03:00",
"id": "01M4YQV7RC6VKAVJM5E6B4TCY8"
},
"channel": "email",
"message": {
"tracking_code": "",
"message_id": "1s9KpQ-0004Zx-2H",
"message_id_relay": "1s9KpR-0007Bd-9K",
"subject": "Seu pedido 1234",
"body": null,
"from": "pedidos@cliente.com.br",
"from_visible": "Loja ",
"to": "destinatario@provedor.com.br",
"recipients": [
"destinatario@provedor.com.br"
],
"tags": [
"transacional",
"pedido-1234"
],
"smtp_domain_id": 4180,
"smtp_account_id": 9271,
"plan_type": "smtp",
"attachments_dropped": [],
"sent_at": "2026-10-15T09:11:58-03:00",
"id": ""
},
"delivery": {
"status": "msg:yes:finished:with:bounce",
"hard_bounce": 1,
"soft_bounce": 0,
"discarded": 0,
"trap": 0,
"bounce": {
"kind": "hard",
"code": "550",
"answer": "550 5.1.1 The email account does not exist",
"domain": "exemplo.com.br"
},
"recipients": [
{
"email": "destinatario@provedor.com.br",
"domain": "exemplo.com.br",
"kind": "hard",
"code": "550",
"answer": "550 5.1.1 The email account does not exist",
"discard_reason": null
}
]
},
"engagement": null
},
"id": "01M4YQV7RC6VKAVJM5E6B4TCY8"
}
```
| Campo | O que é |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `id` | o identificador do **fato**, igual ao cabeçalho `X-iPORTO-Event-Id` |
| `event` | o nome do evento, igual ao cabeçalho `X-iPORTO-Event` |
| `api_version` | a data em que este formato foi fixado |
| `created_at` | quando o evento foi emitido |
| `data` | a mensagem — os campos estão em [O bloco `param.details`](/api/webhooks/eventos/#o-bloco-paramdetails) |
`api_version` não muda quando ganhamos um campo
Acrescentar chave em `data` é livre nos dois formatos — e você recebe sem fazer nada. A versão marca mudança de contrato, e mudança de contrato significa um formato novo, não alteração deste.
## Os nomes de evento
[Seção intitulada “Os nomes de evento”](#os-nomes-de-evento)
| v1 | v2 |
| --------------------------------------------- | -------------------- |
| `msg_deliverability_yes_queue` | `email.queued` |
| `msg_deliverability_yes_delivery` | `email.delivered` |
| `msg_deliverability_not_delivery_soft_bounce` | `email.bounced.soft` |
| `msg_deliverability_not_delivery_hard_bounce` | `email.bounced.hard` |
| `msg_deliverability_not_accepted` | `email.rejected` |
| `msg_engagement_open` | `email.opened` |
| `msg_engagement_click` | `email.clicked` |
| `msg_engagement_compliance_spam` | `email.complained` |
| `msg_deliverability_yes_delivery` (SMS) | `sms.accepted` |
| `msg_deliverability_not_accepted` (SMS) | `sms.rejected` |
O cabeçalho `X-iPORTO-Event` **acompanha o corpo**: nome antigo no v1, novo no v2. Se você casa o cabeçalho com o campo `event`, continua casando.
## `email.delivered` passa a significar “entregue”
[Seção intitulada “email.delivered passa a significar “entregue””](#emaildelivered-passa-a-significar-entregue)
É a única mudança de comportamento, e ela importa
No **v1**, `msg_deliverability_yes_delivery` sai para **toda** mensagem processada, e os eventos de falha são somados a ele. Uma mensagem que voltou inteira gera os dois — e quem lê o primeiro conclui o contrário do que aconteceu.
No **v2**, `email.delivered` sai **só quando não houve bounce nem descarte**. O que houve sai como `email.bounced.hard`, `email.bounced.soft` ou `email.rejected`.
**Entrega parcial não gera `email.delivered`.** Três destinatários, dois entregues e um com hard bounce: sai só `email.bounced.hard`. Quantos de cada desfecho está em `data.delivery`:
```json
{
"status": "msg:yes:finished:with:bounce",
"hard_bounce": 1,
"soft_bounce": 0,
"discarded": 0,
"trap": 0
}
```
Se o seu relatório conta entregas pelo número de eventos `delivered`, no v2 ele passa a contar pelos contadores — e aí ele passa a estar certo nos casos parciais, onde antes contava a mensagem inteira como entregue.
## Os três eventos que só o v2 tem
[Seção intitulada “Os três eventos que só o v2 tem”](#os-três-eventos-que-só-o-v2-tem)
Todos de SMS:
| Evento | Quando acontece |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| `sms.delivered` | o **aparelho** confirmou o recebimento. No v1 isso não tem evento: lá, `yes_delivery` significa “a operadora aceitou” |
| `sms.replied` | o destinatário respondeu — e o texto vem em `data.message.body` |
| `sms.unsubscribed` | a resposta pediu para parar (`SAIR`, `PARE`, `PARAR`, `STOP`) |
`SAIR` gera dois eventos
É uma resposta **e** um descadastro. Se você assina os dois, recebe os dois, com `id` diferentes. E quando o `sms.unsubscribed` chega, **o número já está bloqueado** do nosso lado — você pode consultar e confiar.
## O que o v2 não leva
[Seção intitulada “O que o v2 não leva”](#o-que-o-v2-não-leva)
* **`http_request_params`**, que no v1 repete a sua requisição de envio inteira, incluindo o corpo da mensagem. Se o seu endpoint grava o que recebe, no v1 ele guarda o conteúdo dos seus e-mails; no v2 não há o que guardar.
* **`about`** e o `email`/`phone` do topo: tudo está em `data`.
## Trocar de formato
[Seção intitulada “Trocar de formato”](#trocar-de-formato)
Na tela do endpoint, em **Trocar o formato do corpo**. Vale do próximo evento em diante.
| | |
| ----------------------------------------- | ---------------------------------------------------------------- |
| a troca é **por endereço** | um endpoint em v2 e outro em v1, na mesma conta, é normal |
| endereço **novo** nasce v2 | para usar o v1 nele, troque depois de criar |
| **não** mexe nos eventos que você assinou | as marcações continuam as mesmas |
| o v2 exige **https** | endereço em `http://` tem a troca recusada, com o motivo na tela |
| voltar para o v1 é um clique | os eventos que só existem no v2 deixam de ser enviados |
Prepare o seu sistema antes de trocar
O corpo muda no evento seguinte ao clique. Um endpoint que espera `param` e recebe `data` responde erro — e dez falhas consecutivas desativam o endereço, conforme [Repetição e falhas](/api/webhooks/repeticao-e-falhas/).
O caminho sem risco: use o botão **Testar** de cada evento depois de trocar, com o seu sistema já atualizado, antes de o tráfego real chegar.
# Entender a repetição e as falhas dos webhooks
> O que acontece quando o seu endereço não responde, quantas tentativas existem, quando o endereço é desativado e como acompanhar cada disparo.
Nem todo envio chega de primeira: o seu sistema pode estar fora do ar, lento ou recusando. Esta página descreve o que a iPORTO faz em cada caso — e o que acontece quando as tentativas acabam.
Vale para e-mail, Prospecção e SMS
As mensagens da Prospecção saem pelo canal de e-mail, então o que está descrito aqui — seis tentativas, desativação por falha, histórico com reenvio — vale para elas do mesmo jeito.
## O que conta como sucesso
[Seção intitulada “O que conta como sucesso”](#o-que-conta-como-sucesso)
Só resposta **2xx**. Qualquer outra, ou nenhuma resposta dentro de **15 segundos**, é falha.
| Resposta do seu endereço | O que fazemos |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **2xx** | entrega concluída |
| **408**, **429**, **5xx**, timeout, falha de DNS ou de TLS | nova tentativa |
| **3xx** (redirecionamento) | falha definitiva — não seguimos redirecionamento; configure o endereço final |
| demais **4xx** | falha definitiva: é recusa do seu lado, e repetir não muda o resultado |
Redirecionamento não é seguido
Um `301` para o endereço novo parece inofensivo e é tratado como falha definitiva. Se o seu endereço mudou, troque-o na tela do endpoint.
## As tentativas
[Seção intitulada “As tentativas”](#as-tentativas)
São **6 tentativas**, com esperas de **1, 5 e 30 minutos, 2 horas e 8 horas** — uma janela de aproximadamente **10 horas e 36 minutos** entre a primeira tentativa e a última.
O número da tentativa vem no cabeçalho `X-iPORTO-Attempt`, começando em `1`. Esgotadas as tentativas, a entrega é marcada como **abandonada**.
Responda rápido e processe depois
Aceite com 2xx e trate o evento de forma assíncrona. Um endpoint que faz o trabalho pesado antes de responder estoura os 15 segundos, recebe a mesma entrega de novo — e o trabalho é refeito.
## Quando o endereço é desativado
[Seção intitulada “Quando o endereço é desativado”](#quando-o-endereço-é-desativado)
**Dez entregas abandonadas consecutivas desativam o endereço**, e você recebe um e-mail avisando.
Desativado, ele **para de receber tudo** — e os eventos ocorridos nesse período **não são reenviados** depois. A reativação é na tela do endpoint, no botão **Reativar endpoint**, e zera o contador de falhas.
Uma entrega bem-sucedida zera o contador: dez falhas **seguidas** são necessárias. Os envios do botão **Testar** contam como qualquer outro.
Resposta 429 não conta para a desativação
Pedir ritmo menor é o oposto de endpoint quebrado. As tentativas acontecem, mas a sequência de abandonos não avança.
### O que dá para recuperar depois de reativar
[Seção intitulada “O que dá para recuperar depois de reativar”](#o-que-dá-para-recuperar-depois-de-reativar)
Depende de quando o evento aconteceu:
| Quando | O que fazer |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Antes** da desativação | As entregas abandonadas ficam no **Histórico de Disparos** por 7 dias, cada uma com o botão [Reenviar](#reenviar) |
| **Durante** a desativação | Nenhuma entrega foi criada para o endereço, então não há o que reenviar. Consulte `GET /api/external/v1/messages` com `sent_since` e `sent_until` cobrindo o período: a resposta traz o estado de cada mensagem, na mesma forma do bloco [`param.details`](/api/webhooks/eventos/#o-bloco-paramdetails) |
## Acompanhar cada disparo
[Seção intitulada “Acompanhar cada disparo”](#acompanhar-cada-disparo)
No painel de e-mail (SMTP), em **Webhook → Histórico de Disparos**, você vê cada envio. Clicando em um disparo, o detalhe traz:
* os cabeçalhos que foram enviados;
* o corpo enviado;
* o código de resposta e o corpo que o seu sistema devolveu;
* o número de tentativas e o motivo da falha, quando houve.
O histórico é mantido por **7 dias**.
### Reenviar
[Seção intitulada “Reenviar”](#reenviar)
O detalhe do disparo tem o botão **Reenviar**, que cria um **envio novo** — o registro do envio anterior é preservado. O reenvio vai para o endereço configurado **hoje**, não para o endereço que estava configurado quando o evento aconteceu.
É o caminho para confirmar uma correção no seu endpoint sem depender de uma mensagem nova.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| O histórico mostra **abandonada** em todos os disparos | O endereço não responde 2xx — fora do ar, erro no seu código, ou autorização recusando | Abra o detalhe do disparo e leia o corpo da resposta do seu sistema; é ele que diz o motivo |
| O histórico mostra falha com motivo de **timeout** | O processamento do seu lado passa de 15 segundos | Responda 2xx antes de processar |
| Os eventos pararam e chegou e-mail de aviso | Dez abandonos consecutivos desativaram o endereço | Corrija a causa e clique em **Reativar endpoint**; para o período desativado, ver [O que dá para recuperar](#o-que-d%C3%A1-para-recuperar-depois-de-reativar) |
| Disparos com **4xx** e sem nova tentativa | Recusa definitiva do seu lado — rota inexistente, autorização inválida, corpo recusado | Confira a rota e o token configurado em **Método de Autorização** |
| Disparos com **413** (corpo grande demais) | O seu servidor limita o tamanho do corpo, e o evento cresceu: todo corpo traz `param.details` | Aumente o limite do seu servidor; ver [O bloco `param.details`](/api/webhooks/eventos/#o-bloco-paramdetails) |
| O mesmo evento aparece em dois disparos | Você cadastrou mais de um endereço para o canal | É esperado: o `X-iPORTO-Event-Id` é o mesmo nos dois, e o `X-iPORTO-Delivery` é diferente |
| Um disparo antigo não oferece **Reenviar** | Disparos anteriores à versão atual do histórico não têm o registro necessário para repetir o envio | O detalhe explica o motivo na própria tela |
# Verificar a assinatura dos webhooks
> Confirmar que um evento recebido veio da iPORTO, com código pronto em PHP e Node.js, e tratar a rotação do segredo.
O seu endereço de webhook é público: qualquer um que o descubra pode enviar um `POST` para ele. A assinatura é o que separa o evento que a iPORTO enviou de um que alguém montou.
## Antes de começar
[Seção intitulada “Antes de começar”](#antes-de-começar)
* O **segredo de assinatura**, gerado na tela do endpoint — **Webhook → Endpoints**, abra o endereço e clique em **Gerar segredo**. Ele aparece uma única vez, e cada endpoint tem o seu.
* Acesso ao **corpo cru** da requisição no seu framework — o texto como ele chegou, antes de qualquer interpretação de JSON.
Um segredo por endpoint, em todos os canais
O segredo é gerado na tela do endpoint. No painel de **e-mail** e no de **Prospecção** — que são a mesma configuração e valem para os eventos dos dois — e também no de **SMS**.
## Como a assinatura é montada
[Seção intitulada “Como a assinatura é montada”](#como-a-assinatura-é-montada)
Todo envio leva o cabeçalho:
```plaintext
X-iPORTO-Signature: t=1760313600,v1=5a6f...c3
```
* `t` é o instante do envio em segundos (epoch);
* `v1` é o `HMAC-SHA256` de `"{t}.{corpo cru}"`, com o seu segredo como chave, em hexadecimal.
A conferência tem três partes: recalcular o HMAC, comparar com o que chegou, e recusar envio antigo pela diferença entre `t` e a hora atual.
Assine o corpo CRU, byte a byte
Não serialize de novo o JSON já interpretado. Ordem de chave, escape de barra e precisão de número mudam os bytes, e a verificação falharia sobre uma entrega correta.
Trate `v1` como LISTA
Durante as 24 horas de uma rotação, o cabeçalho traz **dois** valores `v1` — um por segredo válido, na ordem novo, anterior. Aceite se **qualquer** um conferir.
Um verificador que leia só o último valor — e é o que acontece ao transformar o cabeçalho em objeto, com `Object.fromEntries` e parentes — pega o segredo **anterior**: quem já publicou o novo recusaria 100% dos eventos durante a janela inteira.
## PHP
[Seção intitulada “PHP”](#php)
```php
function webhookAssinaturaValida(string $header, string $secret, string $body, int $tolerancia = 300): bool
{
$t = null;
$assinaturas = [];
foreach (explode(',', $header) as $par) {
[$chave, $valor] = array_pad(explode('=', trim($par), 2), 2, null);
if ($chave === 't') {
$t = $valor;
}
// ⚠️ LISTA, não um valor só: durante a rotação o cabeçalho traz DOIS `v1`.
if ($chave === 'v1') {
$assinaturas[] = $valor;
}
}
if ($t === null || $assinaturas === []) {
return false;
}
// Recusa envio antigo: sem isto, quem capturar um envio pode reenviá-lo depois.
if (abs(time() - (int) $t) > $tolerancia) {
return false;
}
$esperado = hash_hmac('sha256', $t.'.'.$body, $secret);
foreach ($assinaturas as $candidata) {
// `hash_equals` e não `===`: comparação de tempo constante.
if (is_string($candidata) && hash_equals($esperado, $candidata)) {
return true;
}
}
return false;
}
```
No Laravel, o corpo cru é `$request->getContent()`.
## Node.js
[Seção intitulada “Node.js”](#nodejs)
```js
const crypto = require('crypto');
function webhookAssinaturaValida(header, secret, body, tolerancia = 300) {
let t = null;
const assinaturas = [];
for (const par of header.split(',')) {
const [chave, valor] = par.trim().split('=');
if (chave === 't') t = valor;
// ⚠️ LISTA, não um valor só: durante a rotação o cabeçalho traz DOIS `v1`.
if (chave === 'v1') assinaturas.push(valor);
}
if (!t || assinaturas.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > tolerancia) return false;
const esperado = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
return assinaturas.some((candidata) => {
const a = Buffer.from(esperado);
const b = Buffer.from(candidata);
// `timingSafeEqual` exige tamanhos iguais; diferente já é inválido.
return a.length === b.length && crypto.timingSafeEqual(a, b);
});
}
```
No Express, use `express.raw({ type: 'application/json' })` para ter o corpo cru.
## Trocar o segredo sem perder evento
[Seção intitulada “Trocar o segredo sem perder evento”](#trocar-o-segredo-sem-perder-evento)
A troca é na tela do próprio endpoint, e a janela de 24 horas existe para você publicar o novo sem recusar o que chegar no meio.
1. Na tela do endpoint, clique em **Gerar segredo** e copie o valor.
2. Publique o segredo novo no seu sistema, mantendo o anterior aceito — o código acima já faz isso, porque compara contra todos os `v1` do cabeçalho.
3. Depois de 24 horas, o anterior deixa de ser enviado e você pode removê-lo da sua configuração.
## Se der errado
[Seção intitulada “Se der errado”](#se-der-errado)
| Sintoma | Causa provável | O que fazer |
| --------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Nenhuma assinatura confere, em todos os eventos | O corpo foi interpretado e serializado de novo antes do cálculo | Use o corpo cru, como ele chegou |
| Todos os eventos passam a falhar logo depois de girar o segredo | O verificador lê um `v1` só, e pegou o anterior | Trate `v1` como lista e aceite se qualquer um conferir |
| Falha intermitente, sem padrão | Relógio do seu servidor fora de hora, contra a tolerância de 5 minutos | Sincronize o relógio por NTP |
| O cabeçalho `X-iPORTO-Signature` não chega | O endpoint ainda não tem segredo gerado | Clique em **Gerar segredo** na tela do endpoint |
| A assinatura confere, mas o evento parece repetido | É retentativa, e isso é esperado | Descarte repetição pelo `X-iPORTO-Delivery` — ver [Receber eventos por webhook](/api/webhooks/) |