This is the full developer documentation for iPORTO # Documentação iPORTO > Como usar cada serviço da iPORTO pelo painel e como integrar o seu sistema por API. Ajuda O que fazer no painel, passo a passo, organizado pelo serviço que você contratou: SMTP, Marketing, E-mail Marketing, Validador de E-mail, SMS e Prospecção. [Começar por aqui →](/ajuda/) API Como o seu sistema acessa a iPORTO sem passar pelo painel: chaves de API e autenticação. [Começar por aqui →](/api/) # Página não encontrada > O endereço acessado não existe nesta documentação. O endereço que você acessou não existe — ou existia e mudou de lugar. **Use a busca no topo da página.** Ela cobre a Ajuda e a API ao mesmo tempo, então funciona mesmo quando você não sabe de que lado está a resposta. * [Ajuda — como fazer no painel](/ajuda/) * [API — como integrar o seu sistema](/api/) # Ajuda — começar por aqui > Onde encontrar cada coisa na documentação de uso da iPORTO. Esta seção responde “como faço isso no painel”. Ela é organizada pelo **serviço** que você usa — cada um tem o próprio painel e os próprios passos — e, dentro de cada serviço, pela tarefa que você quer cumprir. Novo por aqui? Comece por [Entrar na iPORTO e abrir o painel de um serviço](/ajuda/primeiros-passos/entrar-e-abrir-um-servico/). ## Os serviços [Seção intitulada “Os serviços”](#os-serviços) | Área | Responde | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **[E-mail (SMTP)](/ajuda/smtp/adicionar-um-dominio/)** | Envio transacional pelo seu sistema: domínio, DNS, credenciais, conexão, histórico e entregabilidade | | **[Marketing](/ajuda/marketing/criar-uma-marca/)** | Campanhas de e-mail no painel Marketing: marcas, domínio, listas, importação, campanhas e disparos | | **[E-mail Marketing](/ajuda/email-marketing/adicionar-um-dominio/)** | O painel anterior de campanhas, para quem já era cliente: domínio, listas, importação, campanhas e campos de troca | | **[Validador de E-mail](/ajuda/validador-de-email/validar-um-endereco/)** | Conferir endereços antes de enviar, um a um ou em lista | | **[SMS](/ajuda/sms/)** | Mensagens curtas para alertas, confirmações e códigos — em preparação | | **[Prospecção](/ajuda/prospeccao/)** | Sequências de abordagem por e-mail — em preparação | | **[Financeiro](/ajuda/financeiro/entender-sua-assinatura/)** | Assinatura, faturas, pagamento (PIX, boleto, cartão), atraso, créditos, carteira e nota fiscal | | **[Atendimento](/ajuda/atendimento/abrir-um-chamado/)** | Abrir, acompanhar e avaliar chamados com o suporte | | **[Conta](/ajuda/conta/gerenciar-sua-conta/)** | O portal do cliente: acesso e senha, seus dados e os da empresa, notificações, exclusão da conta | Marketing ou E-mail Marketing? São dois painéis diferentes. Se você abre o serviço em `marketing.iporto.com.br`, use a área **Marketing**. Se abre em `email-marketing.iporto.com.br`, use **E-mail Marketing**. ## Como ler um artigo [Seção intitulada “Como ler um artigo”](#como-ler-um-artigo) Todo artigo tem a mesma forma: * **O passo a passo** usa o caminho do menu em negrito — `Infraestrutura → Domínios (SMTP)`. * **“O que acontece depois”** diz o efeito real: o que muda depois da configuração. * **“Se der errado”** lista sintoma, causa e saída. Comece por aqui quando algo não funcionou como você esperava. Procurando a API? Se a pergunta é “como integro isso no meu sistema”, a resposta está em [API](/api/). A busca no topo cobre as duas seções ao mesmo tempo. # Abrir um chamado > Pedir ajuda ao suporte da iPORTO pelo portal, escolher a prioridade certa e saber o prazo de resposta. O chamado é o canal oficial com o suporte da iPORTO: cada pedido fica registrado, com prazo de resposta e histórico da conversa. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, vá em **Suporte → Abrir Chamado** (ou use o ícone de suporte no topo da página). 2. Preencha: * **Assunto** — o que você precisa, numa linha; * **Descrição** — o que aconteceu, e o que você esperava que acontecesse; * **Tipo** — por exemplo, **Financeiro** para fatura e nota fiscal, **Técnico** para problema de envio, **Conta** para acesso e cadastro; * **Prioridade** — veja a tabela abaixo. 3. Se aparecer **Informações adicionais**, preencha: são campos que a iPORTO pede para aquele tipo de chamado. 4. Clique em **Abrir chamado**. O que ajuda o suporte a resolver mais rápido Num problema de envio, informe o serviço, o domínio, o destinatário, o horário e — se tiver — o código de rastreamento ou o Message ID que aparece no histórico do serviço. Num assunto financeiro, o número da fatura. ## O prazo de resposta [Seção intitulada “O prazo de resposta”](#o-prazo-de-resposta) Ao escolher a prioridade, a tela mostra **Prazo que assumimos — até** a data e a hora. Os prazos contam em horário comercial, de segunda a sexta: | Prioridade | Prazo | | ---------- | -------- | | Crítica | 2 horas | | Urgente | 8 horas | | Alta | 24 horas | | Normal | 48 horas | | Baixa | 98 horas | Escolha a prioridade pelo impacto real: **Crítica** é serviço parado; uma dúvida é **Normal**. Se o suporte mudar a prioridade, você recebe uma mensagem no chamado com o motivo e o novo prazo. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * O chamado aparece em **Suporte → Meus Chamados** como **Aberto**. * Anexos (prints, arquivos de log) são enviados **depois** de abrir: entre no chamado e use **Anexos**, com arquivos de até 20 MB. * Para acompanhar, responder e avaliar, veja [Acompanhar, responder e avaliar um chamado](/ajuda/atendimento/acompanhar-um-chamado/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Não acho onde anexar o arquivo | Anexo entra depois de abrir o chamado | Abra o chamado e anexe na página dele | | Não consigo entrar no portal para abrir o chamado | Problema de acesso à conta | Veja [Entrar no portal e recuperar a senha](/ajuda/conta/entrar-e-recuperar-a-senha/); se não resolver, escreva para **** | | Abri o chamado no tipo errado | — | Use **Editar** na página do chamado para trocar o **Tipo** | # Acompanhar, responder e avaliar um chamado > O que cada status do chamado quer dizer, como responder, reabrir, avaliar o atendimento e quem é avisado das respostas. Depois de aberto, o chamado é uma conversa com o suporte: você acompanha o andamento, responde, envia arquivos e, no fim, avalia o atendimento. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, vá em **Suporte → Meus Chamados**. Use os filtros para ver só os abertos, os resolvidos etc. 2. Clique em **Ver chamado** para abrir a conversa. 3. Para responder, escreva em **Conversação** e clique em **Enviar** (ou **Ctrl+Enter**). 4. Para enviar um arquivo, use **Anexos** (até 20 MB). ## O que cada status quer dizer [Seção intitulada “O que cada status quer dizer”](#o-que-cada-status-quer-dizer) | Status | O que significa | | ---------------- | --------------------------------------------------------------------------------- | | **Aberto** | Recebido, esperando o suporte | | **Em Andamento** | O suporte está trabalhando nele | | **Aguardando** | O suporte espera uma resposta ou informação sua — o prazo de resposta fica parado | | **Resolvido** | O suporte considera resolvido; falta a sua confirmação | | **Fechado** | Encerrado. Não aceita mais mensagens | ## Resolvido: confirmar ou reabrir [Seção intitulada “Resolvido: confirmar ou reabrir”](#resolvido-confirmar-ou-reabrir) Quando o chamado está **Resolvido**: * se está tudo certo, avalie em **Como foi o atendimento?** — de 1 a 5 estrelas, com comentário opcional — e clique em **Enviar avaliação**. **Avaliar encerra o chamado.** * se não está resolvido, clique em **Não considero resolvido — Reabrir**, ou simplesmente responda na conversa: a resposta reabre o chamado. Um chamado **Resolvido** sem resposta sua por **7 dias** é fechado automaticamente. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Responder um chamado **Aguardando** ou **Resolvido** devolve ele para **Aberto**. * Todos os usuários da sua conta veem todos os chamados da empresa. * **Quem é avisado das respostas do suporte** — por e-mail e no portal — é **quem abriu o chamado** e os **administradores** da conta. O ícone de suporte no topo do portal mostra quantos chamados estão em aberto. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Não recebi aviso da resposta | O aviso foi para o spam, ou está desligado em **Notificações → Preferências** | Confira o spam e as preferências; o chamado está sempre em **Meus Chamados** | | Não consigo responder | O chamado está **Fechado** | Abra um chamado novo, citando o número do anterior | | O botão **Excluir chamado** não aparece | O chamado já tem mensagens ou anexos | Chamado com conversa não pode ser excluído | | Fechou antes de eu responder | Ficou 7 dias como **Resolvido** sem resposta | Abra um chamado novo citando o anterior | # Atualizar seus dados, os da empresa e os endereços > Onde mudar os seus dados pessoais, o cadastro da empresa (razão social, CPF/CNPJ) e os endereços de cobrança. O portal guarda três cadastros diferentes, e cada um serve a uma coisa: | Cadastro | O que é | Onde | | -------------------- | -------------------------------------------------------- | ------------------------------ | | **Perfil** | Você, a pessoa que entra no portal | **Conta → Perfil** | | **Dados da Empresa** | A empresa cliente da iPORTO — é o que vai na nota fiscal | **Conta → Dados da Empresa** | | **Endereços** | Endereços de cobrança, usados no cartão e na nota fiscal | **Endereços → Meus Endereços** | ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Seus dados pessoais** 1. Em **app.iporto.com.br**, vá em **Conta → Perfil**. 2. Em **Dados pessoais**, ajuste nome, telefone, documento, cargo, fuso horário e idioma. 3. Clique em **Salvar alterações**. Para trocar o e-mail de acesso, veja [Trocar o e-mail e a senha, e encerrar sessões](/ajuda/conta/email-senha-e-sessoes/). **Os dados da empresa** 1. Vá em **Conta → Dados da Empresa**. 2. Ajuste o **Nome** (razão social), o nome de exibição, o **Documento** (CPF ou CNPJ), o telefone, o **E-mail de contato** e o site. 3. Clique em **Salvar alterações**. **Os endereços** 1. Vá em **Endereços → Meus Endereços** e clique em **Adicionar endereço**. 2. Preencha **CEP**, **Rua / Avenida**, **Número**, complemento, **Bairro**, **Cidade** e **Estado (UF)**. 3. Escolha o **Tipo** (por exemplo, **Cobrança**) e, se quiser, marque **Definir como endereço principal**. 4. Clique em **Salvar endereço**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A **nota fiscal** sai com o nome, o documento e o endereço do cadastro **no momento da emissão** — mantenha-os em dia antes de pedir uma nota. Veja [Pedir e baixar a nota fiscal](/ajuda/financeiro/nota-fiscal/). * O cartão de crédito usa o endereço de cobrança escolhido no cadastro do cartão. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ---------------------------------------------- | ------------------------------------------- | ------------------------------------------ | | Ao digitar o CEP, aparece “CEP não encontrado” | A busca automática não encontrou o CEP | Preencha os campos do endereço manualmente | | A nota fiscal saiu com o nome antigo | O cadastro foi atualizado depois da emissão | Peça a substituição da nota no chamado | | O documento não é aceito | CPF ou CNPJ com dígito inválido | Confira os números | # Trocar o e-mail e a senha, e encerrar sessões > Mudar o e-mail de acesso, trocar a senha e desconectar o portal de outros aparelhos. O e-mail e a senha são o seu acesso ao portal e, por ele, a todos os painéis da iPORTO. Este artigo mostra como trocar os dois e como tirar o acesso de aparelhos que você não usa mais. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Trocar o e-mail de acesso** 1. Em **app.iporto.com.br**, vá em **Conta → Perfil**. 2. Em **Alterar e-mail**, informe o novo e-mail e a sua senha atual. 3. Clique em **Alterar e-mail**. **Trocar a senha** 1. Vá em **Conta → Segurança**. 2. Em **Alterar senha**, informe a **Senha atual**, a **Nova senha** e confirme. 3. Clique em **Atualizar senha**. A senha precisa ter pelo menos 8 caracteres, com maiúscula, minúscula e número, e não pode estar em listas públicas de vazamento. **Encerrar sessões** 1. Vá em **Conta → Segurança**, em **Sessões ativas**. Cada aparelho aparece com o IP e a última atividade; o atual está marcado como **Esta sessão**. 2. Clique em **Encerrar** numa sessão, ou em **Encerrar todas as outras sessões**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * **E-mail:** a troca vale na hora — o próximo login já é com o e-mail novo. O portal pede que você confirme o endereço pelo e-mail que chega na caixa nova. * **Senha:** trocar a senha **não** desconecta os outros aparelhos. Se trocou por suspeita de acesso indevido, use também **Encerrar todas as outras sessões**. * **Sessões:** **Encerrar todas as outras sessões** age na hora, sem pedir confirmação. As chaves de API dos serviços não são afetadas. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------- | | O novo e-mail não é aceito | Já existe outro usuário com esse e-mail na conta | Use outro e-mail | | “Senha atual” incorreta | — | Se não lembra a senha, saia e use **Esqueceu a senha?** | | Vejo uma sessão que não reconheço | Alguém pode ter a sua senha | Troque a senha e clique em **Encerrar todas as outras sessões** | | Depois de trocar o e-mail, não consigo entrar | Você está usando o e-mail antigo | Entre com o novo | # Entrar no portal e recuperar a senha > Fazer login no portal do cliente, criar uma senha nova quando esquecer e o que fazer se o link não funcionar. O portal do cliente, em **app.iporto.com.br**, é a entrada da sua conta iPORTO: é por ele que você abre os painéis dos serviços, paga faturas e fala com o suporte. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Entrar** 1. Acesse **app.iporto.com.br**. 2. Informe o **E-mail** e a **Senha** e clique em **Entrar**. **Esqueci a senha** 1. Na tela de login, clique em **Esqueceu a senha?**. 2. Informe o e-mail da conta e clique em **Enviar link de redefinição**. 3. Abra o e-mail e clique no link. 4. Em **Criar nova senha**, digite a senha nova duas vezes e clique em **Salvar nova senha**. 5. Clique em **Ir para o login** e entre com a senha nova. A senha precisa ter pelo menos 8 caracteres, com letra maiúscula, letra minúscula e número. Senhas que aparecem em listas públicas de vazamento são recusadas. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * O link de redefinição vale por **48 horas** e funciona **uma vez só**. * A tela diz “Se o e-mail estiver cadastrado, você receberá um link…” mesmo quando o e-mail não existe — é proposital, para ninguém descobrir quais e-mails têm conta. * Trocar a senha **não** desconecta os outros aparelhos onde a conta já estava aberta. Para isso, use **Encerrar todas as outras sessões** — veja [Trocar o e-mail e a senha, e encerrar sessões](/ajuda/conta/email-senha-e-sessoes/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------ | | O e-mail de redefinição não chega | Foi para o spam, ou o e-mail digitado não é o da conta | Confira o spam e tente com outro e-mail que você possa ter usado | | “Link inválido” | O link passou de 48 horas ou já foi usado | Peça outro em **Esqueceu a senha?** | | A senha nova é recusada | Não atende às regras, ou aparece em lista de vazamento | Use uma senha mais longa, com maiúscula, minúscula e número | | Não lembro qual e-mail usei | — | Escreva para **** com o nome da empresa e o CPF/CNPJ | | A conta não entra mesmo com a senha certa | Conta suspensa | Escreva para **** | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Entrar na iPORTO e abrir o painel de um serviço](/ajuda/primeiros-passos/entrar-e-abrir-um-servico/) # Excluir a conta > Quem pode pedir, o que precisa estar resolvido antes, os 30 dias para desistir e o que é apagado. Excluir a conta apaga os seus dados pessoais e encerra o acesso ao portal e a todos os painéis da iPORTO. Há um prazo de 30 dias para desistir. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Só um **administrador** da conta pode pedir a exclusão. * A conta não pode ter: **assinatura** viva (ativa, em teste, pausada ou em atraso), **fatura em aberto** ou **saldo na carteira**. A tela lista o que estiver impedindo. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, vá em **Conta → Perfil**, até a **Zona de perigo**. 2. Clique em **Excluir minha conta**. 3. Se houver pendências, resolva-as primeiro — a tela mostra quais são. 4. Digite a frase de confirmação pedida (o identificador da sua conta) e a sua senha. 5. Confirme em **Excluir conta**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A conta fica **agendada para exclusão** por **30 dias** e continua funcionando nesse período. Para desistir, volte em **Conta → Perfil** e clique em **Cancelar exclusão**. * Você recebe um e-mail quando a exclusão é agendada, se for cancelada e quando for concluída. * Passados os 30 dias, os dados pessoais são anonimizados, os arquivos apagados e os acessos encerrados. O e-mail e o CPF ficam livres para um cadastro novo. * Faturas e pagamentos são guardados, sem os dados pessoais. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------ | --------------------------------- | ----------------------------------------------------------------------------- | | A tela mostra “Assinatura ativa” | Há assinatura viva | Peça o cancelamento das assinaturas por um chamado e aguarde o fim do período | | A tela mostra “Faturas em aberto” | Há fatura pendente ou em atraso | Pague as faturas em aberto | | A tela mostra “Saldo em carteira” | Há saldo na carteira | Abra um chamado para combinar o uso do saldo | | A exclusão é recusada mesmo sem pendências | Você não é administrador da conta | Peça a um administrador | # O portal do cliente — onde fica cada coisa > O mapa do portal do cliente — dados, segurança, assinatura, faturas, créditos, chamados e notificações. Tudo o que é da sua conta — e não do uso de um serviço específico — fica no **portal do cliente**, em **app.iporto.com.br**: seus dados, a assinatura, as faturas, os créditos, os chamados e os avisos. Os painéis dos serviços (SMTP, Marketing, Validador…) cuidam só do uso de cada um. ## Onde fica cada coisa [Seção intitulada “Onde fica cada coisa”](#onde-fica-cada-coisa) | No menu do portal | O que você encontra | Ajuda | | ---------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Conta → Perfil** | Seus dados pessoais, o e-mail de acesso, a exclusão da conta | [Atualizar seus dados](/ajuda/conta/atualizar-seus-dados/) · [E-mail, senha e sessões](/ajuda/conta/email-senha-e-sessoes/) · [Excluir a conta](/ajuda/conta/excluir-a-conta/) | | **Conta → Segurança** | Senha e sessões ativas | [E-mail, senha e sessões](/ajuda/conta/email-senha-e-sessoes/) | | **Conta → Dados da Empresa** | Razão social, CPF/CNPJ, contato — o que vai na nota fiscal | [Atualizar seus dados](/ajuda/conta/atualizar-seus-dados/) | | **Suporte** | Abrir chamado, acompanhar chamados, perguntas frequentes | [Abrir um chamado](/ajuda/atendimento/abrir-um-chamado/) · [Acompanhar um chamado](/ajuda/atendimento/acompanhar-um-chamado/) | | **Financeiro → Assinatura** | Planos contratados, período, próxima cobrança, cartão da assinatura, troca de plano e cancelamento | [Entender a sua assinatura](/ajuda/financeiro/entender-sua-assinatura/) · [Trocar de plano](/ajuda/financeiro/trocar-de-plano/) · [Cancelar](/ajuda/financeiro/cancelar-uma-assinatura/) | | **Financeiro → Faturas** | Faturas, pagamento e nota fiscal | [Pagar uma fatura](/ajuda/financeiro/pagar-uma-fatura/) · [Nota fiscal](/ajuda/financeiro/nota-fiscal/) | | **Financeiro → Cartões de Crédito** | Cartões de cobrança | [Cartão de cobrança](/ajuda/financeiro/cartao-de-cobranca/) | | **Financeiro → Carteira** e **Créditos** | Saldo em dinheiro e créditos de uso dos serviços | [Créditos e carteira](/ajuda/financeiro/creditos-e-carteira/) | | **Financeiro → Planos Disponíveis** | Contratar outro serviço ou pacote | [Contratar outro serviço](/ajuda/financeiro/contratar-outro-servico/) | | **Endereços → Meus Endereços** | Endereços de cobrança | [Atualizar seus dados](/ajuda/conta/atualizar-seus-dados/) | | **Usuários → Membros** | Logins da sua equipe no portal | [Dar acesso para a sua equipe](/ajuda/conta/membros-da-equipe/) | | **Notificações** | Caixa de entrada e preferências de aviso | [Notificações](/ajuda/conta/notificacoes/) | A página inicial do portal resume a conta: faturas vencidas (com o botão **Regularizar**), chamados em aberto e, em **Aplicações Disponíveis**, os serviços — com **Acessar** para os contratados. Veja [Entrar na iPORTO e abrir o painel de um serviço](/ajuda/primeiros-passos/entrar-e-abrir-um-servico/). De dentro de qualquer painel de serviço, o menu da sua conta (canto superior direito) leva direto a **Minha conta**, **Assinatura e plano** e **Faturas**, em **Portal do cliente**. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------- | | Não consigo entrar no portal | Senha esquecida ou e-mail diferente | Veja [Entrar no portal e recuperar a senha](/ajuda/conta/entrar-e-recuperar-a-senha/) | | Preciso dar acesso a um colega | — | Veja [Dar acesso ao portal para a sua equipe](/ajuda/conta/membros-da-equipe/) | | Uma fatura aparece em aberto, mas você já pagou | O pagamento ainda não foi identificado | Abra um chamado em **Suporte → Abrir Chamado** com o comprovante | # Dar acesso ao portal para a sua equipe > Criar um login para um colega, escolher a função, passar a senha e remover quem saiu da empresa. Cada pessoa da sua equipe pode ter o próprio login no portal do cliente, em vez de todos usarem o mesmo. Assim, quem sai da empresa perde o acesso sem que ninguém precise trocar senha. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Só o **proprietário** da conta (a função **Owner**) ou um **Admin** pode criar e remover membros. Para os demais, o botão **Novo membro** aparece desativado. * O e-mail do novo membro não pode já ter conta no portal da iPORTO, nesta empresa ou em outra. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Criar um membro** 1. Em **app.iporto.com.br**, vá em **Usuários → Membros** e clique em **Novo membro**. 2. Em **Identificação**, preencha o **Nome completo** e o **E-mail** — e, se quiser, telefone, cargo e departamento. 3. Em **Acesso**, escolha a **Função**: **Admin**, **Suporte**, **Financeiro** ou **Marketing**. 4. Clique em **Criar membro**. 5. A tela mostra o e-mail e a **senha gerada**. **Copie e guarde agora** — a senha não será exibida novamente. 6. Passe o e-mail e a senha para o colega por um canal seguro. **Nenhum e-mail é enviado** a ele. **Alterar ou remover um membro** * Na lista, use **Abrir** para ver o membro. Em **Acesso e permissões** dá para mudar a **Função**, o **Status** (por exemplo, suspender) e marcar **Forçar troca de senha**. * Para tirar o acesso de vez, use **Remover** no menu da linha. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * O membro entra em **app.iporto.com.br** com o e-mail e a senha que você passou. Peça que ele troque a senha no primeiro acesso, em **Conta → Segurança** — ou marque **Forçar troca de senha**. * **A função não restringe o que a pessoa vê no portal**: todo membro vê as faturas, os cartões, as assinaturas e os chamados da empresa. A função **Admin** acrescenta gerenciar os membros e excluir a conta. As demais funções organizam a equipe. * Membro removido ou suspenso perde o acesso. * O proprietário da conta não pode ser alterado nem removido por outro membro. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ---------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------- | | **Novo membro** está desativado | Você não é o proprietário nem Admin | Peça a quem é | | O e-mail não é aceito | O e-mail já tem conta no portal da iPORTO | Use outro e-mail da pessoa, ou abra um chamado | | Perdi a senha gerada antes de passar ao colega | Ela aparece uma vez só | O colega usa **Esqueceu a senha?** na tela de login, com o e-mail cadastrado | | O colega saiu da empresa | — | **Remover** na lista de membros | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Trocar o e-mail e a senha, e encerrar sessões](/ajuda/conta/email-senha-e-sessoes/) # Notificações e preferências de aviso > Onde ficam os avisos da sua conta, quais chegam por e-mail e WhatsApp, e como escolher o que receber. A iPORTO avisa os acontecimentos da sua conta — fatura nova, vencimento próximo, pagamento confirmado ou recusado, atraso, resposta de chamado. Os avisos ficam no portal e chegam por e-mail; os mais urgentes, também por WhatsApp. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Ver os avisos** 1. Em **app.iporto.com.br**, clique no sino no topo da página para ver os mais recentes, ou vá em **Notificações → Caixa de Entrada** para ver todos. 2. Use **Todas** ou **Não lidas** para filtrar, e **Marcar todas como lidas** para limpar. **Escolher o que receber** 1. Vá em **Notificações → Preferências**. 2. Para cada evento, marque ou desmarque os canais: **E-mail**, **In-App** (no portal). 3. Clique em **Salvar preferências**. ## Os avisos que a iPORTO envia [Seção intitulada “Os avisos que a iPORTO envia”](#os-avisos-que-a-iporto-envia) | Aviso | Por onde chega | | ------------------------------------ | ----------------------------------------------------------------------------- | | Fatura emitida | E-mail e portal | | Fatura vence em breve (5 dias antes) | E-mail e portal | | Fatura vencida | E-mail, portal e **WhatsApp** | | Pagamento recusado | E-mail, portal e **WhatsApp** | | Pagamento confirmado | E-mail e portal | | Resposta ou encerramento de chamado | E-mail e portal, para quem abriu o chamado e para os administradores da conta | A coluna **SMS** aparece nas preferências, mas a iPORTO não envia avisos da conta por SMS. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------- | | Os e-mails não chegam | Foram para o spam, ou o evento está desmarcado em **Preferências** | Confira o spam e as preferências | | Não recebo aviso de resposta de chamado | O chamado foi aberto por outra pessoa, e você não é administrador | Acompanhe por **Suporte → Meus Chamados** | | O WhatsApp não chega | O telefone do cadastro está desatualizado | Confira o telefone em **Conta → Perfil** e em **Conta → Dados da Empresa** | # Adicionar um domínio e uma conta de autenticação > Cadastrar o domínio das campanhas no E-mail Marketing e criar a conta que autentica os envios. As campanhas saem do domínio da sua empresa, autenticadas por uma **conta de autenticação** desse domínio. Os dois são configurados uma vez e servem a todas as campanhas. Qual painel é este? Os artigos desta área são do **E-mail Marketing** (`email-marketing.iporto.com.br`), o painel anterior, que segue no ar para quem já era cliente. Se você contratou o **Marketing**, veja a área [Marketing](/ajuda/marketing/criar-uma-marca/). ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) Use um domínio **seu**. Remetentes de e-mail gratuito (Gmail, Hotmail, Outlook, Live) fazem a campanha ser cancelada. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do E-mail Marketing, vá em **Domínios de Autenticação** e clique em **Novo domínio**. 2. Em **Domínio**, digite o domínio da sua empresa — por exemplo, `suaempresa.com.br` — e clique em **Criar**. 3. Abra o domínio na lista e publique os registros de DNS — veja [Configurar o DNS do domínio](/ajuda/email-marketing/configurar-o-dns/). 4. Ainda no domínio, abra **Contas de Autenticação** e clique em **Nova conta de autenticação**. Em **Conta**, digite a parte antes do `@` — por exemplo, `news` para `news@suaempresa.com.br` — e clique em **Criar**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * O domínio fica disponível em alguns minutos. * A conta de autenticação é o que você escolhe ao configurar o envio de cada campanha — veja [Criar e enviar uma campanha](/ajuda/email-marketing/criar-e-enviar-uma-campanha/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------- | | Ao configurar o envio: “Nenhuma Conta de autenticação encontrada” | O domínio não tem conta de autenticação | Crie uma em **Domínios de Autenticação → (o domínio) → Contas de Autenticação** | | O domínio não é aceito | Já está cadastrado, ou é de um provedor de e-mail gratuito | Use o domínio da sua empresa; se ele já está em outra conta, abra um chamado | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Configurar o DNS do domínio](/ajuda/email-marketing/configurar-o-dns/) # Personalizar com campos de troca > Inserir nome, telefone e outros dados de cada contato no assunto e no conteúdo das campanhas do E-mail Marketing. Campos de troca são marcações entre colchetes que, no envio, viram o dado de cada contato: `Olá, [name]` chega como “Olá, Ana” para a Ana. Funcionam no assunto e no conteúdo. Quanto mais dados você importar de cada contato, mais campos dá para usar. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Importe os contatos com o máximo de dados — veja [Importar contatos](/ajuda/email-marketing/importar-contatos/). 2. No editor da campanha, digite o campo onde quiser o dado, com os colchetes: `[name]`. 3. Envie um teste para conferir. ## Os campos [Seção intitulada “Os campos”](#os-campos) | Campo | Conteúdo | | ------------------------ | --------------------------- | | `[name]` | Nome | | `[email]` | E-mail | | `[domain]` | Domínio do e-mail | | `[identifier]` | Identificador | | `[phone1]` | Telefone principal | | `[phone2]` | Telefone secundário | | `[address_street]` | Endereço (rua) | | `[address_number]` | Número | | `[address_neighborhood]` | Bairro | | `[address_complement]` | Complemento | | `[address_city]` | Cidade | | `[address_state]` | Estado | | `[address_zipcode]` | CEP | | `[birthday]` | Aniversário | | `[gender]` | Gênero | | `[document_number]` | Número do documento | | `[document_type]` | Tipo do documento | | `[field1]` a `[field9]` | Campos personalizados 1 a 9 | **Links** | Campo | Conteúdo | | --------------- | ------------------------------------------------------------- | | `[unsubscribe]` | Link para o contato gerenciar a inscrição e deixar de receber | | `[view]` | Link para ver o e-mail no navegador | ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Contato sem o dado recebe o campo **em branco** — “Olá, “ em vez de “Olá, Ana”. Use campos que todos os contatos têm preenchidos, ou escreva o texto de forma que funcione sem o dado. * Sem `[unsubscribe]` no conteúdo, um rodapé de gerenciamento de inscrição é acrescentado automaticamente. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------- | | O campo saiu escrito no e-mail, com colchetes | Grafia errada (`[nome]` em vez de `[name]`) | Use exatamente os nomes da tabela, em minúsculas | | O dado saiu em branco | O contato não tem aquele dado cadastrado | Complete os dados importando de novo com **Atualizar o contato caso já exista?** ligado | # Configurar o DNS do domínio > Quais registros SPF, DKIM e de rastreamento publicar para as campanhas do E-mail Marketing, e o DMARC recomendado. Os registros de DNS provam aos provedores de e-mail que a iPORTO pode enviar em nome do seu domínio. Sem eles, as campanhas chegam como suspeitas — vão para o spam ou são recusadas. ## 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](/ajuda/email-marketing/adicionar-um-dominio/). * Tenha 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 E-mail Marketing, vá em **Domínios de Autenticação** e abra o domínio. 2. Abra a aba **DNS**. A tabela mostra **Tipo**, **Nome**, **TTL** e **Valor** de cada registro. 3. Crie no painel de DNS do seu domínio: | 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 | | **Rastreamento** | CNAME | `track-s1` | Mede aberturas e cliques com o seu domínio nos links | 4. Crie também o **DMARC**, que a tela não mostra mas os provedores esperam encontrar: um registro TXT com o nome `_dmarc` e o valor `v=DMARC1; p=none; rua=mailto:dmarc@suaempresa.com.br` (troque pelo seu domínio). O registro track-s2 A tela também mostra um CNAME `track-s2`. Ele não é mais usado e não precisa ser criado. Um SPF só por domínio O domínio só pode ter **um** registro TXT começando com `v=spf1`. Se já existe um, não crie outro: acrescente o `include` da iPORTO ao registro existente, como em `v=spf1 include:spf.smtp-avancado.com include:_spf.google.com ~all`. Use o `include` exato que aparece na tela. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) Mudanças de DNS podem levar de 24 a 48 horas para se propagar. Os provedores também olham se o domínio tem **MX** (recebe e-mail) e um **site** no ar: um domínio que envia mas não recebe nem tem site parece descartável, e isso pesa contra a entrega. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Campanhas indo para o spam | SPF, DKIM ou DMARC ausentes ou incorretos | Confira os três no seu DNS | | Dois registros SPF no domínio | Um SPF novo foi criado em vez de editar o existente | Junte os dois num registro só | | DKIM inválido | O nome foi criado com o domínio repetido, ou o valor foi colado pela metade | Use o nome `mail._domainkey` e cole o valor inteiro | | O rastreamento não funciona | O CNAME `track-s1` não existe, ou está com proxy ligado | Crie o CNAME; na Cloudflare, deixe o proxy desligado (nuvem cinza) | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Criar uma lista de contatos](/ajuda/email-marketing/criar-uma-lista/) # Criar e enviar uma campanha > Montar a campanha no E-mail Marketing, testar, configurar o remetente e agendar o envio para o público certo. A campanha é criada uma vez e pode ser enviada de novo para outros públicos — em vez de criar a mesma campanha várias vezes, reenvie mudando o público. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * O domínio e uma conta de autenticação precisam existir — veja [Adicionar um domínio e uma conta de autenticação](/ajuda/email-marketing/adicionar-um-dominio/). * O público precisa existir: contatos importados, uma lista ou uma segmentação. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Criar e montar** 1. No painel do E-mail Marketing, vá em **E-mail Marketing** e clique em **Nova campanha**. 2. Em **Nome**, dê um nome que ajude a achar a campanha depois e clique em **Criar**. 3. Monte o conteúdo no editor, arrastando os elementos para o corpo da mensagem. Salve. 4. Na aba **E-mail Marketing**, preencha o **Assunto do E-mail** e o **Conteúdo “Preview”** (o texto que aparece ao lado do assunto na caixa de entrada). Clique em **Salvar**. 5. Use **Envio de Teste**: informe um e-mail em **E-mail para Recebimento (de um Teste)** e clique em **Enviar um Teste**. Confira como a mensagem chega. **Configurar o envio** 6. Abra **Envio**. Na aba **Remetente**, preencha **Nome**, **E-mail** e **E-mail para Respostas** e salve. 7. Na aba **Conta de Autenticação**, escolha a conta do domínio que vai autenticar o envio. **Enviar** 8. Clique em **Enviar e-mail marketing**. Em **Agendamento de envio**: * em **Público que será impactado**, escolha **Todos os Contatos**, **Conjunto de Listas de Contatos** ou **Uma Segmentação**; * em **Data de Envio**, escolha quando enviar; * se quiser, ative as opções de filtro de público, como deixar de fora contatos com baixo engajamento. 9. Clique em **Enviar**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) A campanha é enviada na hora ou fica agendada para a data escolhida. Remetente gratuito cancela a campanha Se o e-mail do remetente for `@gmail.com`, `@hotmail.com`, `@live.com` ou `@outlook.com`, a campanha é cancelada no envio. Use sempre um endereço do seu domínio. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------- | | A campanha não saiu / aparece cancelada | O remetente é um e-mail gratuito | Troque o **E-mail** do remetente por um endereço do seu domínio | | “Você precisa escolher, primeiro, uma Conta de Autenticação…” | Nenhuma conta foi escolhida em **Envio** | Escolha a conta na aba **Conta de Autenticação** | | “Nenhuma Conta de autenticação encontrada” | O domínio não tem conta de autenticação | Crie uma em **Domínios de Autenticação → (o domínio) → Contas de Autenticação** | | O teste chegou no spam | DNS do domínio incompleto | Confira [Configurar o DNS do domínio](/ajuda/email-marketing/configurar-o-dns/) | | Os campos de troca saíram escritos no e-mail | Marcação digitada errado | Confira em [Personalizar com campos de troca](/ajuda/email-marketing/campos-de-troca/) | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Personalizar com campos de troca](/ajuda/email-marketing/campos-de-troca/) # Criar uma lista de contatos > Criar listas no E-mail Marketing para direcionar as campanhas a um público definido. A lista agrupa contatos para que a campanha fale com quem importa — “Clientes”, “Leads do site”, “Newsletter”. Trabalhe só com contatos que autorizaram receber os seus e-mails. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do E-mail Marketing, vá em **Segmentações de Funil** e escolha **Lista de Contatos**. 2. Clique em **Nova lista de contatos**. 3. Em **Nome**, use um nome que diga quem está na lista, e clique em **Criar**. Repita para cada lista de que precisar. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) A lista nasce vazia. Para colocar contatos nela, veja [Importar contatos](/ajuda/email-marketing/importar-contatos/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------- | -------------------------------------------------------------------------- | ----------------------- | | Não acho a lista criada | Está em **Segmentações de Funil → Lista de Contatos**, não em **Contatos** | Abra pelo caminho certo | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Importar contatos](/ajuda/email-marketing/importar-contatos/) # Importar contatos > Enviar uma planilha CSV ou TXT para o E-mail Marketing e dizer o que é cada coluna. A importação traz os seus contatos de uma planilha para o E-mail Marketing. Quanto mais dados de cada contato você trouxer, mais dá para personalizar e segmentar depois. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * O arquivo deve ser **CSV** ou **TXT**, com colunas separadas por vírgula, e ter até **50 MB**. (A tela de envio fala em 250 MB, mas arquivos acima de 50 MB são recusados.) * Importe só contatos que autorizaram receber os seus e-mails. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do E-mail Marketing, abra a lista em **Segmentações de Funil → Lista de Contatos** (ou vá em **Contatos**) e clique em **Enviar Lista de Contatos**. 2. Em **Anexo de planilha**, escolha o arquivo no seu computador. 3. Na tela **Configuração de arquivo e importação**: * deixe ligado **A primeira linha indica as colunas do arquivo?** se a primeira linha tiver os nomes das colunas; * deixe ligado **Atualizar o contato caso já exista?** para que os dados novos do arquivo completem contatos já cadastrados. 4. Em **Como as colunas devem ser interpretadas?**, o painel mostra o valor da primeira linha de cada coluna. Escolha, em **Relacionamento da Coluna**, o que cada uma é — por exemplo: | Valor | Relacionamento da Coluna | | ------------------- | ------------------------ | | `Maria Souza` | Nome completo | | `maria@exemplo.com` | E-mail | | `17/02/1984` | Aniversário | Além desses, há Telefone 1 e 2, as partes do endereço, Gênero, Número e Tipo de Documento, Identificador e os **Campos personalizados 1 a 9**. 5. Clique em **Salvar**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) A importação começa em seguida. O tempo depende do tamanho do arquivo. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- | | “Seu arquivo pode ter no máximo 50M de tamanho” | Arquivo maior que 50 MB | Divida em arquivos menores | | As colunas vieram todas juntas num campo só | O arquivo não está separado por vírgula | Salve a planilha de novo como CSV separado por vírgula | | O cabeçalho virou um contato | **A primeira linha indica as colunas do arquivo?** ficou desligado | Exclua o contato errado e, na próxima importação, ligue a opção | | Dados de contatos existentes não mudaram | **Atualizar o contato caso já exista?** estava desligado | Importe de novo com a opção ligada | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Criar e enviar uma campanha](/ajuda/email-marketing/criar-e-enviar-uma-campanha/) * [Personalizar com campos de troca](/ajuda/email-marketing/campos-de-troca/) # Cancelar uma assinatura > Cancelar pelo portal, até quando o serviço funciona, e o cuidado com a fatura que chega antes da renovação. O cancelamento é feito pelo próprio portal e vale no **fim do período já pago**: até lá, o serviço continua funcionando normalmente. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) Cancele com mais de 10 dias de antecedência A fatura do próximo período é gerada **10 dias antes** da renovação. Se você cancelar **depois** que ela foi gerada, o cancelamento só acontece no fim do período seguinte — e essa fatura continua valendo e é cobrada no vencimento. Se a fatura do próximo período já chegou e você quer cancelar, **abra um chamado** antes, pedindo o cancelamento e o da fatura — veja [Abrir um chamado](/ajuda/atendimento/abrir-um-chamado/). ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, vá em **Financeiro → Assinatura**. 2. No card da assinatura, clique em **Cancelar** (ou, no detalhe, em **Cancelar assinatura**). 3. A tela **Cancelar Assinatura** mostra a assinatura e a data de **Acesso garantido até**. 4. Se quiser, conte o motivo: **Motivo**, **Comentário** e **Você voltaria a usar no futuro?** — tudo opcional, mas ajuda a iPORTO a melhorar. Se não preencher nada, a tela pede para clicar de novo para confirmar. 5. Clique em **Confirmar cancelamento**. Para desistir, clique em **Manter assinatura**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A tela mostra **Cancelamento agendado**, e a assinatura passa a exibir o selo **Cancela no fim do período**. * O serviço segue funcionando até a data de **Acesso garantido até**. Nenhuma fatura nova é gerada para essa assinatura depois do agendamento. * No fim do período, a assinatura passa a **Cancelado**: * os créditos que restavam nela expiram; * as faturas em aberto que eram só dela são canceladas; * os complementos ligados a ela são cancelados junto. * O cancelamento **não gera reembolso automático** do período em curso. * **Mudou de ideia?** Até a data de encerramento, clique em **Desfazer cancelamento** no card da assinatura (ou no detalhe). A assinatura volta a renovar normalmente. * Para voltar a usar o serviço depois, contrate-o de novo — veja [Contratar outro serviço](/ajuda/financeiro/contratar-outro-servico/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ---------------------------------------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Cancelei e chegou uma fatura do próximo período | O cancelamento foi feito depois que a fatura antecipada foi gerada | Abra um chamado pedindo o cancelamento da fatura | | Quero desistir do cancelamento, mas a assinatura já está **Cancelado** | O período terminou e o cancelamento foi executado | Contrate o serviço de novo, ou abra um chamado | | Não aparece o botão **Cancelar** | A assinatura já está cancelada, expirada ou com cancelamento agendado | Confira o status em **Financeiro → Assinatura** | | O serviço parou antes da data de **Acesso garantido até** | Há fatura em atraso na assinatura | Veja [O que acontece quando o pagamento atrasa](/ajuda/financeiro/pagamento-em-atraso/) | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Entender a sua assinatura](/ajuda/financeiro/entender-sua-assinatura/) * [Excluir a conta](/ajuda/conta/excluir-a-conta/) # Cadastrar e trocar o cartão de cobrança > Adicionar um cartão, escolher o cartão padrão e definir qual cartão paga cada assinatura. Com um cartão cadastrado, a iPORTO cobra as renovações automaticamente, sem você precisar abrir a fatura. Este artigo mostra como cadastrar, trocar e remover cartões. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) O cartão precisa de um **endereço de cobrança**. Se você ainda não tem um, o portal leva ao cadastro de endereço antes — veja [Atualizar seus dados, os da empresa e os endereços](/ajuda/conta/atualizar-seus-dados/). ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) **Cadastrar um cartão** 1. Em **app.iporto.com.br**, vá em **Financeiro → Cartões de Crédito** e clique em **Adicionar cartão**. 2. Preencha o **Nome impresso no cartão**, o **Número do cartão** (a bandeira é reconhecida sozinha), o CVV, o mês e o ano de validade e escolha o endereço de cobrança. 3. Se quiser, dê um **Apelido do cartão** e marque **Definir como cartão padrão**. 4. Clique em **Salvar cartão**. **Escolher o cartão padrão ou remover um cartão** Na lista de cartões, abra o menu da linha e escolha **Definir como padrão** ou **Remover cartão**. **Escolher o cartão de uma assinatura** 1. Vá em **Financeiro → Assinatura** e clique em **Ver** na assinatura. 2. No bloco **Método de pagamento**, escolha o cartão em **Cartão de crédito** — ou deixe **Usar cartão padrão (selecionado automaticamente)**. 3. Clique em **Salvar método de pagamento**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * As próximas faturas daquela assinatura são cobradas no cartão escolhido, com até 3 tentativas até o vencimento — veja [Quando a fatura chega e quando vence](/ajuda/financeiro/quando-a-fatura-chega-e-vence/). * Trocar o cartão **não** cobra faturas que já estão em aberto. Para essas, pague pela fatura — veja [Pagar uma fatura](/ajuda/financeiro/pagar-uma-fatura/). * Os dados do cartão ficam guardados de forma criptografada; o portal mostra só o final do número. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | -------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | O portal me leva para o cadastro de endereço | Cartão exige endereço de cobrança | Cadastre o endereço e volte ao cartão | | “Pagamento não processado” ao usar o cartão | Recusa do banco emissor | Confira os dados, use outro cartão, ou pague por PIX | | O cartão novo não foi usado na renovação | A assinatura estava presa a outro cartão no **Método de pagamento** | Escolha o cartão no detalhe da assinatura, ou volte para **Usar cartão padrão** | | O cartão venceu | Validade expirada | Cadastre o novo, defina como padrão e remova o antigo | # Contratar outro serviço ou pacote > Ver os planos disponíveis, contratar pelo portal e começar a usar o serviço novo. Pelo portal você contrata outros serviços da iPORTO, ou um plano novo de um serviço que já usa, sem precisar falar com ninguém. O serviço contratado aparece na sua conta assim que o pagamento é confirmado. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, use um dos dois caminhos: * na página inicial, em **Aplicações Disponíveis**, clique em **Contratar** no card do serviço; * ou vá em **Financeiro → Planos Disponíveis** e use **Filtrar por aplicação**. 2. Compare os planos. **Ver detalhes** mostra os recursos e os preços por periodicidade. 3. Clique em **Assinar plano** — ou em **Iniciar teste grátis**, nos planos com teste. 4. No checkout, escolha a **Periodicidade**, confira o resumo e, se tiver, use **Tenho um cupom de desconto**. 5. Escolha a forma de pagamento — PIX, boleto ou cartão (à vista) — e conclua. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Com o pagamento confirmado (PIX e cartão em instantes, boleto em até 3 dias úteis), a assinatura aparece em **Financeiro → Assinatura** e o card do serviço passa a mostrar **Acessar** — veja [Entrar na iPORTO e abrir o painel de um serviço](/ajuda/primeiros-passos/entrar-e-abrir-um-servico/). * Nos planos com créditos, eles chegam junto com a ativação. * No teste grátis, a primeira cobrança vem quando o teste acabar. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------- | | “Sua conta foi criada, mas o pagamento não foi concluído” | O pagamento foi recusado ou não terminou | Pague pela fatura que o portal abriu — veja [Pagar uma fatura](/ajuda/financeiro/pagar-uma-fatura/) | | Contratei e o card ainda mostra **Contratar** | O pagamento ainda não foi confirmado | Aguarde a confirmação; o boleto leva até 3 dias úteis | | O plano que eu queria não aparece | Ele não está à venda pelo portal | Abra um chamado | | Quero trocar o plano de um serviço que já tenho | Troca de plano não é uma contratação nova | Veja [Trocar de plano](/ajuda/financeiro/trocar-de-plano/) | # Créditos dos serviços e saldo da carteira > A diferença entre os créditos de uso (envios, validações) e o saldo em dinheiro da carteira, quando cada um chega e quando expira. O portal mostra dois saldos diferentes, e vale não confundir: * **Créditos** são unidades de uso dos serviços — envios de e-mail, de SMS, validações de e-mail. Eles vêm com o plano e são consumidos quando você usa o serviço. * **Carteira** é saldo em **dinheiro**, que a iPORTO desconta das suas próximas faturas. ## Créditos [Seção intitulada “Créditos”](#créditos) 1. Em **app.iporto.com.br**, vá em **Financeiro → Créditos**. 2. Cada tipo de crédito aparece num card, com o saldo **disponíveis**, o total **Concedido** e o **Usado**. 3. A aba **Lotes** mostra cada leva de créditos — quanto foi concedido, usado e quanto resta, e **Válido até**. A aba **Uso por dia** mostra o consumo. **Como funcionam:** * Os créditos chegam na **ativação** do plano e a cada **renovação paga** — chegam quando a fatura é paga, não na data da renovação. * O consumo usa primeiro o lote mais antigo. * Cada lote tem validade. Passada a data de **Válido até**, o que sobrou expira. * Se a assinatura é cancelada, os créditos que restavam nela expiram junto. * O painel de cada serviço também mostra o saldo, no item **Créditos** do menu dele. Para ter mais créditos, contrate um plano ou pacote em **Financeiro → Planos Disponíveis** — veja [Contratar outro serviço](/ajuda/financeiro/contratar-outro-servico/). ## Carteira [Seção intitulada “Carteira”](#carteira) 1. Vá em **Financeiro → Carteira**. 2. Os cards mostram o **Saldo disponível**, o **Total creditado** e o **Total utilizado**; o **Extrato** lista cada entrada e saída. 3. Com **Aplicação automática em faturas** ativada, o saldo é descontado sozinho de cada fatura nova. Desative se preferir guardar o saldo. 4. Para usar o saldo numa fatura que já foi gerada, abra a fatura em **Financeiro → Faturas** e clique em **Usar R$ X da carteira**. **De onde vem o saldo:** de um pagamento feito a mais (por exemplo, a mesma fatura paga duas vezes) ou de um crédito lançado pela iPORTO. O saldo não pode ser sacado nem devolvido em dinheiro — ele serve para pagar faturas. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Os créditos da renovação não chegaram | A fatura da renovação ainda não foi paga | Pague a fatura; os créditos chegam com a confirmação | | Os créditos sumiram | O lote passou da validade, ou a assinatura foi cancelada | Confira **Válido até** na aba **Lotes** | | O serviço recusa envios mesmo com créditos | A assinatura está em atraso | Veja [O que acontece quando o pagamento atrasa](/ajuda/financeiro/pagamento-em-atraso/) | | O saldo da carteira não foi usado numa fatura | **Aplicação automática em faturas** estava desativada quando a fatura foi gerada | Abra a fatura e clique em **Usar R$ X da carteira**; ative a opção para as próximas | | Paguei duas vezes e quero o dinheiro de volta | O valor a mais vira saldo na carteira | Ele é descontado nas próximas faturas; para outro arranjo, abra um chamado | # Entender a sua assinatura > Onde ver o plano contratado, o período atual, a próxima cobrança e o que cada status quer dizer. A assinatura é o plano que você contratou para cada serviço: o que ele inclui, quanto custa, o período em curso e quando vem a próxima cobrança. Cada serviço tem a sua. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Entre no portal do cliente, em **app.iporto.com.br**. 2. No menu lateral, vá em **Financeiro → Assinatura**. Cada assinatura aparece num card com o plano, o status, o preço, o **Período atual**, a **Próxima cobrança**, a **Frequência** e o **Início**. 3. Clique em **Ver** para o detalhe: a composição do valor (preço base, taxa de setup, descontos), as datas, os recursos inclusos no plano e o **Método de pagamento** daquela assinatura. ## O que cada status quer dizer [Seção intitulada “O que cada status quer dizer”](#o-que-cada-status-quer-dizer) | Status | O que significa | | --------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Ativo** | Em dia. O serviço funciona normalmente | | **Trial** | Em período de teste. A primeira cobrança vem quando o teste acabar | | **Aguard. pagamento** | Contratada, esperando o primeiro pagamento para começar | | **Em atraso** | Há fatura vencida e não paga — veja [O que acontece quando o pagamento atrasa](/ajuda/financeiro/pagamento-em-atraso/) | | **Pausado** | Suspensa temporariamente pela iPORTO; o detalhe mostra se há data de retomada | | **Cancelado** | Encerrada | | **Expirado** | Chegou ao fim (por exemplo, um plano de pagamento único com prazo) | Uma assinatura com o selo **Cancela no fim do período** segue funcionando até a data de encerramento e não é renovada. Encerrar o teste antes do prazo Durante o teste, o aviso **Trial ativo** tem o botão **Assinar agora**. Ele encerra o teste na hora e emite a fatura do primeiro ciclo — útil quando você já decidiu e não quer esperar. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A fatura de cada renovação chega antes da data — veja [Quando a fatura chega e quando vence](/ajuda/financeiro/quando-a-fatura-chega-e-vence/). * O **Método de pagamento** do detalhe define o cartão usado nas cobranças automáticas daquela assinatura — veja [Cadastrar e trocar o cartão de cobrança](/ajuda/financeiro/cartao-de-cobranca/). * Para trocar de plano, veja [Trocar de plano](/ajuda/financeiro/trocar-de-plano/); para cancelar, [Cancelar uma assinatura](/ajuda/financeiro/cancelar-uma-assinatura/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | **Trocar Plano** mostra “Nenhuma opção disponível” | O serviço não tem troca pelo portal (E-mail Marketing, SMS) | Peça a troca por um chamado — veja [Trocar de plano](/ajuda/financeiro/trocar-de-plano/) | | A assinatura aparece **Em atraso**, mas você já pagou | O pagamento ainda não foi confirmado (boleto leva até 3 dias úteis) | Confira a fatura em **Financeiro → Faturas**; se já compensou, abra um chamado com o comprovante | | Não vejo a assinatura de um serviço que uso | Ele está em outra conta, ou foi contratado com outro e-mail | Confira o e-mail em **Conta → Perfil** e abra um chamado | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Pagar uma fatura](/ajuda/financeiro/pagar-uma-fatura/) * [Créditos dos serviços e saldo da carteira](/ajuda/financeiro/creditos-e-carteira/) # Pedir e baixar a nota fiscal > Como solicitar a nota fiscal de uma fatura paga e onde baixar o PDF e o XML depois de emitida. A nota fiscal (NFS-e) de uma fatura é emitida **sob pedido**: você solicita pelo atendimento e, depois de emitida, ela fica disponível para download na própria fatura. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) A nota sai com os dados de **Conta → Dados da Empresa**. Confira antes de pedir: * **Nome** (razão social) e **Documento** (CPF ou CNPJ) — obrigatórios; * para CNPJ, um **endereço** em **Endereços → Meus Endereços** — sem ele, a nota sai sem o endereço do tomador. Veja [Atualizar seus dados, os da empresa e os endereços](/ajuda/conta/atualizar-seus-dados/). ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, vá em **Suporte → Abrir Chamado**. 2. Em **Tipo**, escolha **Financeiro**. No assunto, escreva “Nota fiscal” e, na descrição, informe a fatura (o número aparece em **Financeiro → Faturas**). 3. Clique em **Abrir chamado**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A iPORTO emite a nota e responde no chamado. * A nota aparece no detalhe da fatura: **Financeiro → Faturas → Ver**, no bloco **Nota Fiscal**, com o número, o valor, a data de emissão e os botões **Baixar PDF** e **Baixar XML**. * **Não chega aviso automático** quando a nota é emitida — acompanhe pelo chamado ou pela fatura. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------- | | O bloco **Nota Fiscal** não aparece na fatura | A nota ainda não foi emitida | Acompanhe o chamado | | A nota saiu com dados errados | O cadastro em **Dados da Empresa** estava desatualizado na emissão | Corrija os dados e responda no chamado pedindo a substituição | | O status da nota é **Erro** | A emissão foi recusada pela prefeitura ou faltou dado | Responda no chamado; a iPORTO corrige e emite de novo | | Preciso da nota de várias faturas | — | Informe todas no mesmo chamado | # O que acontece quando o pagamento atrasa > O prazo até o serviço parar de funcionar, até a assinatura ser cancelada, e como regularizar. Atrasar uma fatura não corta o serviço na hora: há um prazo até ele parar e outro, maior, até a assinatura ser cancelada. E pagar a qualquer momento antes do cancelamento resolve tudo. ## O calendário do atraso [Seção intitulada “O calendário do atraso”](#o-calendário-do-atraso) Os prazos contam a partir do **vencimento da fatura mais antiga em aberto** daquela assinatura. | Quando | O que acontece | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Vencimento** | A fatura está **Pendente** | | **2 dias depois** (PIX ou boleto) ou **1 dia depois** (cartão) | A fatura passa a **Em atraso** e a assinatura também. Você recebe o aviso por e-mail, no portal e por WhatsApp | | **5 dias depois** | O serviço **para de funcionar**: os envios e as integrações passam a ser recusados com a mensagem “Você não possui um plano ativo. Verifique sua assinatura para continuar utilizando o serviço.” | | **30 dias depois** | A assinatura é **cancelada** | Não há multa nem juros por atraso. ## Regularizar [Seção intitulada “Regularizar”](#regularizar) Pague a fatura em aberto — veja [Pagar uma fatura](/ajuda/financeiro/pagar-uma-fatura/). Assim que o pagamento é confirmado: * a assinatura volta a ficar **Ativo**; * o serviço volta a funcionar; * os créditos do ciclo, nos planos que têm créditos, são liberados. O PIX e o cartão são confirmados em instantes. O boleto leva até 3 dias úteis — se o serviço já parou, prefira o PIX. ## Quando a assinatura é cancelada [Seção intitulada “Quando a assinatura é cancelada”](#quando-a-assinatura-é-cancelada) Depois de 30 dias de atraso: * a assinatura passa a **Cancelado**; * os créditos que restavam nela expiram; * as faturas em aberto que eram só daquela assinatura são canceladas. Uma assinatura cancelada **não volta** com um pagamento. Para usar o serviço de novo, contrate-o outra vez — veja [Contratar outro serviço](/ajuda/financeiro/contratar-outro-servico/) — ou fale com o suporte. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | O painel do serviço abre, mas os envios são recusados | O atraso passou dos 5 dias de carência | Pague a fatura em aberto; com o pagamento confirmado, o serviço volta | | Paguei e o serviço continua parado | O boleto ainda não compensou | Aguarde a compensação (até 3 dias úteis); se já compensou, abra um chamado com o comprovante | | Paguei e a assinatura continua cancelada | O pagamento chegou depois dos 30 dias | Abra um chamado — a assinatura cancelada não volta sozinha | | Não sei qual fatura está em atraso | — | **Financeiro → Faturas**, com o filtro **Em atraso**; a página inicial do portal também mostra “fatura(s) vencida(s)” com o botão **Regularizar** | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Quando a fatura chega e quando vence](/ajuda/financeiro/quando-a-fatura-chega-e-vence/) * [Cadastrar e trocar o cartão de cobrança](/ajuda/financeiro/cartao-de-cobranca/) # Pagar uma fatura (PIX, boleto ou cartão) > Gerar o PIX, o boleto ou pagar com cartão a partir da fatura, e o prazo de cada forma de pagamento. Toda fatura em aberto pode ser paga pelo portal do cliente, na forma que você preferir: PIX, boleto ou cartão de crédito. O pagamento por PIX e cartão é confirmado em instantes; o boleto, em até 3 dias úteis. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Entre em **app.iporto.com.br** e vá em **Financeiro → Faturas**. 2. Na fatura em aberto, clique em **Ver** e depois em **Pagar fatura**. 3. Escolha a forma de pagamento: **PIX** * Aparecem o QR Code e o **Código copia e cola**, com o botão **Copiar**. * O código vale **30 minutos** — o tempo restante aparece na tela. * Depois de pagar no aplicativo do banco, clique em **Já paguei — verificar**. **Boleto bancário** * Aparecem o **Código de barras**, com **Copiar**, e o botão **Baixar boleto (PDF)**. * O boleto vence em **3 dias** e **não pode ser pago depois do vencimento** — se passar, gere outro. * A compensação leva até 3 dias úteis depois do pagamento. **Cartão de crédito** * Escolha um dos **Seus cartões cadastrados** ou clique em **+ Usar outro cartão** e preencha os dados e o endereço de cobrança. * O pagamento é **à vista**. * Clique em **Pagar** com o valor indicado. Se o seu cadastro não tiver telefone, a tela pede um antes de gerar a cobrança. Pagar só uma parte Na janela **Pagar fatura**, desligue **Pagamento total** e informe o valor. A tela mostra o **Saldo restante após este pagamento**. A fatura fica como **Parc. pago**, e o restante segue em aberto na mesma fatura — pague-o da mesma forma, em **Pagar fatura**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Com o pagamento confirmado, a tela mostra “Pagamento confirmado! Sua fatura foi atualizada.” e a fatura passa a **Pago**. * Se a assinatura estava em atraso, ela volta a ficar ativa assim que o pagamento é confirmado — e o serviço volta a funcionar. * Os créditos do ciclo, nos planos que têm créditos, são liberados quando a fatura da renovação é paga. * Um PIX ou boleto já gerado fica guardado na fatura: o card **PIX pronto para pagamento** ou **Boleto pronto para pagamento** reabre o código. Em **Histórico de pagamentos**, o botão **Ver instruções** faz o mesmo. Pague só uma vez Gerar um PIX ou boleto novo não cancela o anterior. Se os dois forem pagos, o valor a mais vira **saldo na sua carteira**, descontado nas próximas faturas — não é devolvido em dinheiro. Veja [Créditos dos serviços e saldo da carteira](/ajuda/financeiro/creditos-e-carteira/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------- | | O QR Code do PIX não funciona mais | Passaram os 30 minutos | Clique em **Gerar nova cobrança ou trocar forma de pagamento** e gere outro | | Paguei o PIX e a fatura continua em aberto | A confirmação do banco ainda não chegou | Aguarde alguns instantes e clique em **Já paguei — verificar** | | O banco recusa o boleto | O boleto venceu — ele não aceita pagamento depois do vencimento | Gere outro boleto pela fatura | | “Pagamento não processado” no cartão | Recusa do banco emissor (limite, dados, bloqueio) | Clique em **Tentar novamente**, use outro cartão, ou pague por PIX | | Não aparece o botão **Pagar fatura** | A fatura já está paga, cancelada ou em negociação | Confira o status na lista de faturas | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Quando a fatura chega e quando vence](/ajuda/financeiro/quando-a-fatura-chega-e-vence/) * [Cadastrar e trocar o cartão de cobrança](/ajuda/financeiro/cartao-de-cobranca/) # Quando a fatura chega e quando vence > Com que antecedência a fatura da renovação é gerada, como o vencimento é definido, os avisos que você recebe e a cobrança automática no cartão. A fatura de cada renovação chega antes da data, para dar tempo de pagar sem pressa. Este artigo explica o calendário: quando ela é gerada, quando vence, os avisos e o que acontece se você tem cartão cadastrado. ## O calendário de uma renovação [Seção intitulada “O calendário de uma renovação”](#o-calendário-de-uma-renovação) | Quando | O que acontece | | ------------------------------ | ---------------------------------------------------------------------------------------------------- | | **10 dias antes** da renovação | A fatura é gerada e aparece em **Financeiro → Faturas**. Você recebe um aviso por e-mail e no portal | | **5 dias antes** do vencimento | Aviso de que a fatura vence em breve | | **Data da renovação** | Vencimento. Se cair num sábado ou domingo, vai para a **segunda-feira** seguinte | Se você tem mais de uma assinatura com o mesmo vencimento e a mesma forma de pagamento, elas vêm **juntas numa fatura só**. ## Cobrança automática no cartão [Seção intitulada “Cobrança automática no cartão”](#cobrança-automática-no-cartão) Se a assinatura tem um cartão de cobrança (veja [Cadastrar e trocar o cartão de cobrança](/ajuda/financeiro/cartao-de-cobranca/)), a iPORTO cobra a fatura nele automaticamente: * são até **3 tentativas**, com intervalo de 24 horas, **até a data de vencimento**; * se nenhuma for aprovada até o vencimento, a fatura passa a ser cobrada por **PIX**, e você recebe o aviso de pagamento recusado — inclusive por WhatsApp. Sem cartão, pague pela própria fatura — veja [Pagar uma fatura](/ajuda/financeiro/pagar-uma-fatura/). ## Saldo da carteira [Seção intitulada “Saldo da carteira”](#saldo-da-carteira) Se você tem saldo na carteira e a **Aplicação automática em faturas** está ativada, o saldo é descontado da fatura no momento em que ela é gerada. Veja [Créditos dos serviços e saldo da carteira](/ajuda/financeiro/creditos-e-carteira/). ## O que cada status da fatura quer dizer [Seção intitulada “O que cada status da fatura quer dizer”](#o-que-cada-status-da-fatura-quer-dizer) | Status | O que significa | | ----------------- | ----------------------------------------------------------------- | | **Pendente** | Esperando pagamento, dentro do prazo | | **Parc. pago** | Parte do valor foi paga | | **Pago** | Quitada | | **Em atraso** | Venceu e não foi paga | | **Em negociação** | Em acordo com a iPORTO; nenhuma cobrança automática enquanto isso | | **Cancelado** | Cancelada antes do pagamento | | **Estornado** | O pagamento foi devolvido | ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | -------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | A fatura chegou bem antes da renovação | É o normal: ela é gerada 10 dias antes | Pague até o vencimento | | Não recebi o aviso da fatura | O e-mail foi para o spam, ou você desligou o aviso em **Notificações → Preferências** | Confira o spam e as preferências; a fatura está sempre em **Financeiro → Faturas** | | O cartão não foi cobrado | O cartão venceu, foi recusado, ou a assinatura não tem cartão de cobrança | Confira o **Método de pagamento** da assinatura e pague a fatura por PIX ou boleto | | Veio uma fatura com vários serviços | Assinaturas com o mesmo vencimento vêm juntas | Os itens da fatura mostram cada serviço | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [O que acontece quando o pagamento atrasa](/ajuda/financeiro/pagamento-em-atraso/) # Trocar de plano > Subir ou descer de plano dentro do mesmo serviço, pelo portal, e como fica a diferença de valor. Você pode trocar o plano de uma assinatura pelo próprio portal — subir para um plano maior ou descer para um menor, dentro do mesmo serviço. A troca vale na hora, e a diferença de valor do período em curso vem na próxima fatura. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * A troca pelo portal está disponível no **SMTP**, na **Prospecção** e no **Marketing**. No **E-mail Marketing** e no **SMS**, a troca é feita pelo suporte — veja [Abrir um chamado](/ajuda/atendimento/abrir-um-chamado/). * A troca é entre planos do **mesmo serviço** e mantém a **periodicidade** (mensal continua mensal). Para passar de mensal para anual, abra um chamado. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Em **app.iporto.com.br**, vá em **Financeiro → Assinatura**. 2. No card da assinatura, clique em **Trocar Plano** (ou, no detalhe, em **Trocar de Plano**). 3. Em **Escolha o novo plano**, cada opção mostra o preço e um selo: **Upgrade**, **Downgrade** ou **Mesmo nível**. Abaixo do preço aparece o ajuste do período atual — **Cobrança proporcional**, **Crédito proporcional** ou **Sem ajuste proporcional**. 4. Escolha o plano. A barra no rodapé mostra o plano **Atual**, o **Novo** e o ajuste. 5. Clique em **Confirmar troca**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A troca vale **na hora**: os recursos do plano novo passam a valer, e a tela mostra “Plano alterado com sucesso!”. Você recebe um aviso da troca por e-mail e no portal. * A **diferença do período em curso** é calculada pelo tempo que falta até a renovação: * ao **subir** de plano, a diferença é cobrada; * ao **descer**, ela vira crédito. Nos dois casos, ela aparece como um item na **próxima fatura** — não há cobrança separada. * Da renovação em diante, as faturas vêm com o preço do plano novo. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | “Nenhuma opção disponível — Não há planos disponíveis para mudança a partir do seu plano atual.” | O serviço não tem troca pelo portal (E-mail Marketing, SMS) ou não há outro plano à venda nele | Peça a troca por um chamado | | O plano que eu queria não aparece | Ele é de outro serviço, de outra periodicidade, ou não está à venda | Para mudar de periodicidade ou de serviço, abra um chamado; para outro serviço, veja [Contratar outro serviço](/ajuda/financeiro/contratar-outro-servico/) | | “Troca de plano disponível novamente em …” | Há um intervalo mínimo entre duas trocas | Aguarde a data indicada | | A troca é recusada por uma troca anterior | A troca anterior ainda está pendente de cobrança | Aguarde a próxima fatura, ou abra um chamado | | “Reduza o uso antes de trocar” | O plano menor não comporta o que você usa hoje | Reduza o uso no serviço (domínios, contatos…) e tente de novo | | Não aparece o botão **Trocar Plano** | A assinatura tem cancelamento agendado, ou está cancelada | Veja [Cancelar uma assinatura](/ajuda/financeiro/cancelar-uma-assinatura/) | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Quando a fatura chega e quando vence](/ajuda/financeiro/quando-a-fatura-chega-e-vence/) # Adicionar um domínio de envio e publicar o DNS > Cadastrar o domínio das campanhas no Marketing e publicar os registros que liberam o envio. As campanhas saem do domínio da sua empresa. Antes do primeiro envio, ele precisa estar cadastrado no Marketing e com os registros de DNS publicados — **sem SPF e DKIM, o disparo não sai**. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Tenha acesso ao painel de DNS do domínio (registro.br, Cloudflare, sua hospedagem…). * Use o domínio principal, sem subdomínio — `suaempresa.com.br`, não `news.suaempresa.com.br`. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do Marketing, vá em **Canais → Domínios de e-mail** e clique em **Novo domínio**. 2. Digite o domínio e clique em **Cadastrar**. Você é levado à página dele. 3. No bloco **Publique os registros de DNS**, copie cada registro (**Nome**, **Valor**, **TTL**) com o botão **Copiar** e crie-o no painel de DNS do domínio: | Registro | Tipo | Nome | Obrigatório? | | ---------------- | ----- | ----------------- | -------------------------------------------------------- | | **SPF** | TXT | o próprio domínio | Sim | | **DKIM** | TXT | `mail._domainkey` | Sim | | **DMARC** | TXT | `_dmarc` | Recomendado | | **Rastreamento** | CNAME | `track-s1` | Recomendado — mede aberturas e cliques com o seu domínio | 4. Aguarde a propagação e acompanhe os selos no topo da página. 5. Se aparecer a ação **Liberar envio deste domínio**, clique nela. Ela cria a credencial de envio que faltava; não há nada a preencher. 6. Ligue o domínio à marca: no card **Marcas que enviam por aqui**, use **Usar este domínio** — ou escolha o domínio no card **Domínio de envio**, na página da marca. Um SPF só por domínio O domínio só pode ter **um** registro TXT começando com `v=spf1`. Se já existe um, não crie outro: acrescente o `include` da iPORTO ao registro existente, como em `v=spf1 include:spf.smtp-avancado.com include:_spf.google.com ~all`. Use o `include` exato que aparece na tela. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * O selo muda de **Não autenticado** para **Autenticado** quando SPF e DKIM são encontrados, e de **Ainda não envia** para **Pode enviar** quando o domínio está pronto para disparar. * Um domínio serve a todas as marcas da conta. * O envio do Marketing usa IP compartilhado — não há escolha de IP aqui. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | -------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | **Não autenticado** depois de publicar | O DNS ainda está propagando, ou há dois registros SPF | Espere algumas horas; confira se existe só um TXT com `v=spf1` | | DKIM não encontrado | O nome foi criado errado — alguns painéis de DNS acrescentam o domínio sozinhos | Cadastre o nome só como `mail._domainkey`, e cole o valor inteiro | | Autenticado, mas **Ainda não envia** | Falta a credencial de envio | Clique em **Liberar envio deste domínio** | | O rastreamento não funciona | O CNAME `track-s1` não existe, ou está com proxy ligado | Crie o CNAME; na Cloudflare, deixe o proxy desligado (nuvem cinza) | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Criar uma lista de contatos](/ajuda/marketing/criar-uma-lista/) * [Criar uma campanha](/ajuda/marketing/criar-uma-campanha/) # Agendar um disparo > Escolher a campanha, o público e o horário, e confirmar o envio. O disparo junta uma campanha pronta a um público e a um horário. A mesma campanha pode ter vários disparos — para públicos diferentes, ou para reenviar em outra data. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * A campanha precisa estar **pronta** — veja [Criar uma campanha](/ajuda/marketing/criar-uma-campanha/). * O público precisa existir: uma lista de contatos ou uma segmentação. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do Marketing, vá em **Envios → Agendamentos** e crie um novo agendamento. 2. Em **O que enviar**, escolha a **Campanha** e, se quiser, dê um **Nome do disparo**. 3. Em **Para quem**, escolha **Segmentação** ou **Lista de contatos** e, em **Alvo**, qual delas. 4. Em **Quando**, escolha a data e a hora — ou deixe em branco para enviar assim que confirmar. 5. Clique em **Criar rascunho**. 6. Na página do agendamento, revise e clique em **Confirmar disparo**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * No horário marcado (ou logo após a confirmação), o envio começa. * Durante o envio, a página do agendamento permite **Pausar envio** e depois **Retomar envio**, ou **Cancelar disparo**. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------- | | A campanha não aparece na lista | Ela ainda é rascunho | Abra a campanha e clique em **Marcar como pronta** | | Quero enviar para todos os contatos | O disparo é sempre para uma lista ou uma segmentação — não há a opção “todos” | Importe a base inteira para uma lista e dispare para ela | | O disparo não começou no horário | Ficou como rascunho, sem **Confirmar disparo** | Abra o agendamento e confirme | | Não consigo criar outro agendamento | O plano limita os agendamentos em andamento | Espere um terminar, ou mude de plano | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Personalizar com variáveis](/ajuda/marketing/personalizar-com-variaveis/) # Criar uma campanha e enviar um teste > Montar o e-mail no editor visual ou em HTML, revisar o remetente, testar e deixar pronto para disparar. A campanha é o e-mail em si: assunto, remetente e conteúdo. Ela é montada uma vez e pode ser disparada para públicos diferentes — o disparo é um passo separado, em [Agendar um disparo](/ajuda/marketing/agendar-um-disparo/). ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) A marca precisa de um domínio de envio autenticado — veja [Adicionar um domínio de envio](/ajuda/marketing/adicionar-um-dominio/). ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do Marketing, vá em **Conteúdo → Campanhas** e crie uma nova campanha. 2. Na tela **Nova Campanha**: * em **Por onde vai sair**, deixe **E-mail**; * em **Identificação**, preencha **Nome** (para você achar a campanha depois) e **Assunto** — o assunto aceita variáveis, como `[name]`; * em **Como você quer montar o e-mail?**, escolha **Editor visual** (arrastar e soltar) ou **HTML próprio** (colar o seu código). 3. Clique em **Criar campanha**. 4. Monte o conteúdo no editor. O card **Variáveis**, ao lado, lista o que dá para personalizar — veja [Personalizar com variáveis](/ajuda/marketing/personalizar-com-variaveis/). Clique em **Salvar conteúdo**. 5. De volta à campanha, preencha o **Pré-cabeçalho** (o texto que aparece ao lado do assunto na caixa de entrada) e confira o **Remetente**. Campo deixado em branco usa o remetente padrão da marca. Clique em **Salvar alterações**. 6. Use a aba **Prévia** com **Ver como** para ver o e-mail com os dados de um contato real. 7. Clique em **Enviar um teste**, informe até 5 endereços separados por vírgula e clique em **Enviar teste**. 8. Quando estiver tudo certo, clique em **Marcar como pronta**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * O teste chega com `[TESTE]` no começo do assunto, não entra nos relatórios e não consome créditos. * Só campanhas **prontas** podem ser disparadas. Para editar de novo, use **Voltar para rascunho**. * **Duplicar campanha** cria uma cópia para reaproveitar o conteúdo. * Se a campanha não tiver link de descadastro (`[descadastro]` ou `[preferencias]`), um rodapé com o link é acrescentado automaticamente no envio. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Aviso de remetente fora do domínio | O e-mail do remetente não é do domínio de envio da marca | Use um endereço `@seudominio`; para receber as respostas em outro, preencha **Responder para** | | Aviso de que a marca não tem domínio de envio | A marca não está ligada a um domínio | Escolha o domínio no card **Domínio de envio**, na página da marca | | Aviso de variável desconhecida | Uma variável foi digitada errado, ou não existe neste painel | Confira no card **Variáveis**; variáveis desconhecidas saem como texto no e-mail | | O botão **Enviar campanha** não aparece | A campanha ainda é rascunho | Clique em **Marcar como pronta** | | O teste não chegou | Foi para o spam, ou o domínio ainda não está autenticado | Procure no spam; confira os selos do domínio em **Canais → Domínios de e-mail** | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Agendar um disparo](/ajuda/marketing/agendar-um-disparo/) # Criar uma lista de contatos > Agrupar contatos numa lista para enviar campanhas a um público definido. A lista é um grupo de contatos que você monta à mão ou por importação — “Clientes”, “Inscritos no evento”, “Newsletter”. É um dos dois públicos que um envio pode ter; o outro é a **segmentação**, que reúne contatos por regra (cidade, data de cadastro…) e se atualiza sozinha. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do Marketing, vá em **Público → Listas de Contatos** e clique em **Nova lista**. 2. Em **Nome da lista**, use um nome que diga quem está nela. O nome não pode se repetir na mesma marca. 3. Se quiser, preencha a **Descrição**. 4. Clique em **Criar lista**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) A lista nasce vazia. Para colocar contatos nela, importe um arquivo — veja [Importar contatos](/ajuda/marketing/importar-contatos/) — e escolha a lista em **Adicionar à lista**. Da página da lista, o botão **Importar contatos** já leva a importação com a lista escolhida. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------- | --------------------------------------------- | ------------------------------------------------- | | O nome não é aceito | Já existe uma lista com esse nome nesta marca | Escolha outro nome | | A lista não aparece | Você está em outra marca | Troque a marca no seletor do topo do menu lateral | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Importar contatos](/ajuda/marketing/importar-contatos/) # Criar uma marca e definir o remetente padrão > Organizar contatos e campanhas por marca e definir com que nome e e-mail as campanhas saem. No Marketing, tudo pertence a uma **marca**: contatos, listas, campanhas e envios. Se a sua empresa fala com o público com um nome só, uma marca basta. Se tem mais de um negócio ou produto, com públicos e identidades diferentes, crie uma para cada. Qual painel é este? Este artigo é do **Marketing** (`marketing.iporto.com.br`). Se você usa o painel anterior, o **E-mail Marketing**, veja os artigos da área [E-mail Marketing](/ajuda/email-marketing/adicionar-um-dominio/). ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do Marketing, vá em **Marcas** e crie uma nova marca. Em **Nome da marca**, use o nome que o seu público reconhece. 2. Abra a marca e clique para editar. No painel **Editar Marca**, preencha: * **Site** e **URL do logo**; * em **Remetente padrão**: **Nome do remetente**, **E-mail do remetente** e **Responder para (Reply-To)**; * em **Rodapé das campanhas**: **Endereço físico** da empresa. 3. Salve. 4. Na página da marca, no card **Domínio de envio**, escolha o domínio pelo qual a marca envia. Se ainda não tem um, veja [Adicionar um domínio de envio](/ajuda/marketing/adicionar-um-dominio/). Para alternar entre marcas, use o seletor no topo do menu lateral; **Gerenciar marcas** leva à lista. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Toda campanha nova da marca já sai com o remetente padrão. Dá para trocar campanha a campanha; campo deixado em branco na campanha usa o da marca. * O **E-mail do remetente** precisa ser um endereço do domínio de envio da marca. Para receber as respostas em outra caixa — no Gmail da equipe, por exemplo —, use **Responder para**. * O **Endereço físico** aparece no rodapé das campanhas. Informar quem envia é exigência das boas práticas de e-mail marketing e ajuda na entrega. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ----------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | A campanha avisa que o remetente está fora do domínio | O **E-mail do remetente** não é do domínio de envio da marca | Use um endereço `@seudominio`; para receber respostas em outro endereço, preencha **Responder para** | | A campanha avisa que a marca não tem domínio de envio | Nenhum domínio foi escolhido no card **Domínio de envio** | Escolha o domínio na página da marca | | Não consigo criar outra marca | O plano permite um número de marcas | Veja o seu plano no portal do cliente | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Adicionar um domínio de envio](/ajuda/marketing/adicionar-um-dominio/) * [Importar contatos](/ajuda/marketing/importar-contatos/) # Importar contatos > Trazer contatos de uma planilha CSV ou TXT, ligar cada coluna a um campo e registrar a origem da autorização. A importação traz os seus contatos de uma planilha para o Marketing, já numa lista se você quiser. ## 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** por envio. * As colunas podem ser separadas por ponto e vírgula (`;`) ou vírgula (`,`) — o painel detecta. * Cada contato precisa de pelo menos um **e-mail** ou um **telefone**. * Datas no formato `AAAA-MM-DD` ou `DD/MM/AAAA`. * Importe só contatos que autorizaram receber os seus e-mails. O painel pede que você registre de onde veio essa autorização. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do Marketing, vá em **Público → Importações** e clique em **Importar contatos**. 2. Em **De onde vêm os contatos**, use **Enviar arquivo** — ou **Colar conteúdo**, para colar o texto direto. Se a primeira linha do arquivo tiver os nomes das colunas, deixe marcado **A primeira linha é o cabeçalho**. 3. Em **Qual coluna é cada campo**, confira a ligação de cada campo com uma coluna do arquivo. O painel liga sozinho as colunas com nome conhecido. Os campos são **E-mail**, **Telefone**, **Nome**, **Aniversário**, **Cidade**, **Estado** e **Identificador**; o que não quiser trazer, deixe em **— não importar —**. 4. Em **O que fazer com eles**: * em **Adicionar à lista**, escolha a lista — ou **Nenhuma lista**; * marque **Atualizar contatos que já existem** para que os dados do arquivo substituam os de contatos já cadastrados. 5. Em **De onde veio a autorização**, escolha a origem — por exemplo, **Preencheram um formulário nosso** ou **São clientes ou fecharam negócio conosco**. Se quiser, detalhe em **Detalhe da origem**. 6. Clique em **Importar contatos**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * A importação roda em segundo plano; acompanhe em **Público → Importações**. O status passa por **Na fila**, **Importando** e **Concluída** — ou **Falhou**. * Linhas que não puderam ser importadas aparecem no detalhe da importação, com o motivo e exemplos das linhas afetadas. * Se o mesmo contato aparecer duas vezes no arquivo, vale a **última** linha. * Se a lista escolhida tiver uma automação de entrada, aparece a opção **Disparar automações para os contatos novos**. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | 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 | | O botão de importar não libera | Nenhuma coluna foi ligada a **E-mail** nem a **Telefone**, ou a origem da autorização não foi escolhida | Ligue a coluna de e-mail (ou telefone) e escolha uma opção em **De onde veio a autorização** | | As colunas vieram todas juntas num campo só | O separador do arquivo não é `;` nem `,` | Salve de novo como CSV separado por ponto e vírgula | | Acentos aparecem trocados | A codificação do arquivo não foi reconhecida | Exporte a planilha de novo como **CSV UTF-8** e importe outra vez | | Parte das linhas não entrou | Linhas sem e-mail nem telefone, ou com dado inválido | Abra a importação em **Público → Importações** e veja os motivos listados | | Aniversários vazios ou errados | Data em formato diferente | Use `AAAA-MM-DD` ou `DD/MM/AAAA` | | O plano não comporta os contatos | O arquivo passa do limite de contatos do plano | A mensagem diz quantas vagas restam; importe menos linhas ou mude de plano | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Criar uma campanha](/ajuda/marketing/criar-uma-campanha/) # Personalizar a campanha com variáveis > Inserir o nome e outros dados de cada contato no assunto e no conteúdo, com valor reserva quando o dado falta. Variáveis são marcações entre colchetes que, no envio, viram o dado de cada contato: `Olá, [name]` chega como “Olá, Ana” para a Ana e “Olá, Bruno” para o Bruno. Funcionam no assunto e no conteúdo. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No editor da campanha, abra o card **Variáveis** para ver a lista completa. 2. Digite a variável onde quiser o dado, com os colchetes: `[name]`. 3. Para quando o dado faltar, use um **valor reserva** depois de uma barra vertical: `[name|Cliente]` sai como “Cliente” para quem não tem nome cadastrado. 4. Confira o resultado na aba **Prévia**, com **Ver como** e um contato real. ## As variáveis [Seção intitulada “As variáveis”](#as-variáveis) **Do contato** | Variável | Conteúdo | | ------------------- | ----------------- | | `[name]` | Nome | | `[email]` | E-mail | | `[domain]` | Domínio do e-mail | | `[phone1]` | Telefone | | `[identifier]` | Identificador | | `[address_city]` | Cidade | | `[address_state]` | Estado | | `[address_zipcode]` | CEP | | `[gender]` | Gênero | | `[birthday]` | Aniversário | | `[created_at]` | Data de cadastro | **Da marca** | Variável | Conteúdo | | ------------------ | ------------------------ | | `[marca.nome]` | Nome da marca | | `[marca.site]` | Site da marca | | `[marca.endereco]` | Endereço físico da marca | **Links** | Variável | Conteúdo | | ---------------- | ---------------------------------------------- | | `[descadastro]` | Link para o contato deixar de receber | | `[preferencias]` | Link para a central de preferências do contato | | `[ver_online]` | Link para ver o e-mail no navegador | ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Variável que o painel não conhece sai **como texto** no e-mail — `[nome]` em vez do nome — e a campanha mostra um aviso antes do envio. * Sem `[descadastro]` nem `[preferencias]` no conteúdo, um rodapé com o link de descadastro é acrescentado automaticamente. Vindo do E-mail Marketing? Algumas marcações do painel anterior não existem aqui: `[unsubscribe]`, `[view]`, `[phone2]`, `[field1]` a `[field9]`, `[document_number]` e as partes de endereço como `[address_street]`. Troque `[unsubscribe]` por `[descadastro]` e `[view]` por `[ver_online]`. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------- | ------------------------------------------------ | -------------------------------------- | | A variável apareceu escrita no e-mail | Nome errado ou variável inexistente neste painel | Confira a grafia no card **Variáveis** | | O nome saiu em branco | O contato não tem nome cadastrado | Use valor reserva: \`\[name | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Criar uma campanha](/ajuda/marketing/criar-uma-campanha/) # Entrar na iPORTO e abrir o painel de um serviço > Onde fazer login, como abrir o painel de cada serviço contratado e por que um login vale para todos. Cada serviço da iPORTO tem o próprio painel — SMTP, Marketing, Validador de E-mail e os demais —, mas a entrada é uma só: o **portal do cliente**, em `app.iporto.com.br`. É lá que você faz login, e é de lá que abre o painel de cada serviço. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) Você precisa de uma conta na iPORTO. Ela é criada na primeira compra, no próprio checkout, ou no cadastro do site. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. Acesse **app.iporto.com.br** e entre com seu e-mail e senha. Se esqueceu a senha, use **Esqueceu a senha?** na mesma tela. 2. Na página inicial do portal, procure **Aplicações Disponíveis**. Cada serviço aparece como um card. 3. No card do serviço, clique em **Acessar**. O painel dele abre numa nova aba, já com você conectado. Depois do primeiro acesso, você pode entrar direto pelo endereço de cada painel — por exemplo, `smtp.iporto.com.br` — enquanto a sessão estiver ativa. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * **Um login vale para todos os painéis.** Ao abrir um serviço, os outros que você contratou também passam a abrir sem pedir login. * **Sair de um painel desconecta de todos os painéis da iPORTO**, mas não do portal do cliente. Para voltar, abra o serviço de novo pelo portal. * Dentro de cada painel, o menu da sua conta (no canto superior direito) tem o atalho **Portal do cliente**, com **Minha conta**, **Assinatura e plano** e **Faturas**. ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | O card mostra **Contratar** em vez de **Acessar** | Você não tem assinatura ativa daquele serviço | Clique em **Contratar** para ver os planos, ou confira a assinatura em **Assinatura e plano** | | O painel abriu e voltou para o portal | O link de acesso vale por poucos segundos e só uma vez; ele expirou antes de o painel abrir | Clique em **Acessar** de novo, no portal | | Ao digitar o endereço de um painel, você cai no portal | Sua sessão nos painéis terminou (ou você saiu de um deles) | Abra o serviço pelo card no portal | | Não encontro o serviço em **Aplicações Disponíveis** | O serviço não faz parte da sua conta | Fale com o suporte por um chamado — veja [Gerenciar sua conta](/ajuda/conta/gerenciar-sua-conta/) | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Adicionar um domínio de envio no SMTP](/ajuda/smtp/adicionar-um-dominio/) * [Criar uma marca no Marketing](/ajuda/marketing/criar-uma-marca/) * [Validar um endereço de e-mail](/ajuda/validador-de-email/validar-um-endereco/) # Prospecção > Sequências de abordagem por e-mail e acompanhamento das respostas — artigos em preparação. A Prospecção organiza abordagens por e-mail em sequências: quem recebe, o que recebe em cada etapa e quando. Os artigos desta área estão em preparação. Em preparação Esta página vai listar cada tarefa — criar um espaço de trabalho, montar uma abordagem, importar contatos, acompanhar as respostas — à medida que os artigos forem publicados. Até lá, para dúvidas, abra um chamado no portal do cliente, em **Suporte → Abrir Chamado**. # SMS > Envio de mensagens curtas para alertas, confirmações e códigos de verificação — artigos em preparação. O SMS da iPORTO envia mensagens curtas para celulares — alertas, confirmações, lembretes e códigos de verificação —, uma a uma ou em campanhas para a sua base de contatos. Os artigos desta área estão em preparação. Em preparação Enquanto os artigos não chegam, para dúvidas sobre o SMS abra um chamado no portal do cliente, em **Suporte → Abrir Chamado** — veja [Gerenciar sua conta](/ajuda/conta/gerenciar-sua-conta/). # A pontuação do seu domínio caiu, e agora? > O que fazer quando a pontuação do domínio cai e os e-mails param de ser entregues, e em quanto tempo ela volta. Quando a pontuação do seu domínio cai, parte dos seus e-mails deixa de ser enviada. Este artigo mostra como descobrir a causa, o que fazer hoje e em quanto tempo o envio volta ao normal. ## O que a pontuação significa na prática [Seção intitulada “O que a pontuação significa na prática”](#o-que-a-pontuação-significa-na-prática) A pontuação vai de 0 a 100 e representa a reputação do seu domínio. Cada provedor de destino exige um mínimo para aceitar mensagens suas: | Sua pontuação | O que ainda é entregue | | ------------- | ------------------------------------------------------------------------- | | 95 ou mais | Todos os destinos | | 90 a 94 | Quase todos; bancos, órgãos federais e grandes multinacionais não recebem | | 85 a 89 | Grandes provedores de e-mail sim; órgãos públicos, Vivo, Claro e TIM não | | 80 a 84 | Gmail sim; Hotmail, Outlook, Yahoo, UOL, Terra e iCloud não | | 75 a 79 | Domínios corporativos `.com.br` sim; Gmail não | | 45 a 74 | Apenas destinos sem exigência própria de pontuação | | Abaixo de 45 | **Nenhum e-mail é enviado** | Se a sua pontuação está abaixo de 45, nada está sendo entregue — e é por isso que o problema aparece de uma vez, e não aos poucos. A pontuação atual aparece em **Infraestrutura → Domínios (SMTP)**, no card **Pontuação Atual**, junto com o que ela impede de entregar. ## Passo 1 — Descubra a causa [Seção intitulada “Passo 1 — Descubra a causa”](#passo-1--descubra-a-causa) Abra o domínio em **Infraestrutura → Domínios (SMTP)**. O card de pontuação mostra a **maior perda** e o que a resolve. Para o detalhe completo, clique em **Histórico de pontuação**: a perda aparece separada por causa. | Perda por | O que significa | | ------------- | --------------------------------------------------------------- | | **DNS** | Falta publicar SPF, DKIM ou os demais registros do domínio | | **Bounce** | Você enviou para endereços que não existem | | **Spam** | Destinatários marcaram suas mensagens como spam | | **Spam Trap** | Sua lista tem endereços-armadilha, usados para identificar spam | A maior perda é por onde começar. ## Passo 2 — Se a perda é por DNS [Seção intitulada “Passo 2 — Se a perda é por DNS”](#passo-2--se-a-perda-é-por-dns) É a causa mais comum, e a de solução mais rápida: sem SPF e DKIM publicados, a pontuação cai para perto de 12 e **nenhum e-mail é enviado**, mesmo que você nunca tenha tido um problema de entrega. Publique os registros e clique em **Verificar agora**, na página do domínio: a pontuação é recalculada em segundos. Se preferir aguardar, a própria página mostra o horário da próxima verificação automática deste domínio. O passo a passo da publicação está em [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/). ## Passo 3 — Se a perda é por bounce [Seção intitulada “Passo 3 — Se a perda é por bounce”](#passo-3--se-a-perda-é-por-bounce) Bounce é o e-mail que volta porque o endereço não existe. A conta olha os **últimos 7 dias**, e os degraus são estes: | Endereços inválidos nos últimos 7 dias | Pontuação | Consequência | | -------------------------------------- | ------------ | ----------------------------------------- | | Até 2% | 90 ou mais | Nenhuma | | Entre 2% e 4% | 60 a 79 | Gmail, Hotmail e Outlook param de receber | | Acima de 4% | Abaixo de 45 | Nenhum e-mail é enviado | Em 1.000 envios, **20 endereços inválidos é o limite seguro**; acima de 40, o envio para por completo. O que fazer agora: 1. **Pare de enviar para quem deu erro.** Em **Envios → Histórico**, filtre pelos envios não entregues e identifique os endereços inválidos. 2. **Não apague a lista de supressão.** Ela é o que impede o reenvio para esses endereços — e reenviar é o que mantém a pontuação baixa. Um bloqueio excluído não pode ser recuperado. 3. **Valide os endereços antes de enviar.** Se eles vêm de um formulário no seu site, veja [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/). Para uma lista que você já tem, use o [Validador de E-mail](/ajuda/validador-de-email/validar-uma-lista/). ## Passo 4 — Acompanhe a recuperação [Seção intitulada “Passo 4 — Acompanhe a recuperação”](#passo-4--acompanhe-a-recuperação) A pontuação é recalculada a cada 4 horas, sempre sobre os **últimos 7 dias**. Cada domínio tem o seu horário: a página do domínio mostra a última e a próxima verificação, e o botão **Verificar agora** antecipa a conta quando você acabou de corrigir algo. Os envios com erro saem da janela de 7 dias com o tempo, e a pontuação sobe sozinha — desde que não entrem erros novos: | Quando | O que esperar | | --------------------------- | ------------------------------------------------------------ | | Na próxima verificação | A pontuação reflete o DNS corrigido | | Ao longo de 7 dias | Os erros antigos saem da janela e a perda por bounce diminui | | Após 7 dias sem novos erros | A perda por bounce chega a zero | A recuperação total da qualidade do remetente leva alguns dias a mais que a pontuação, porque ela considera a média dos últimos 7 dias. ## O que não ajuda [Seção intitulada “O que não ajuda”](#o-que-não-ajuda) | Tentativa | Por que não funciona | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Apagar a lista de supressão | Remove a proteção contra reenviar para endereços inválidos, e os bloqueios não voltam. Tende a piorar a pontuação | | Reenviar para quem deu erro | Cada tentativa conta como novo erro na janela de 7 dias | | Criar um domínio novo para o mesmo envio | O problema está na lista, não no domínio; o novo domínio acumula os mesmos erros | | Enviar mais para “diluir” os erros | A conta é percentual: enviar mais para a mesma lista mantém a proporção | ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | | Status **Descartada antes do envio** no histórico | A pontuação está abaixo do mínimo exigido pelo destino, e a mensagem não chegou a ser enviada | Abra a mensagem: o motivo aparece por destinatário | | Status **Parcialmente descartada** | Parte dos destinatários foi descartada — por pontuação, por estar na lista de supressão ou por erro anterior | Abra a mensagem e confira o motivo de cada um | | A pontuação não subiu depois de corrigir o DNS | A verificação ainda não rodou | Clique em **Verificar agora** na página do domínio | | A pontuação subiu, mas o Gmail ainda não recebe | O Gmail exige 80 | Veja a tabela do início deste artigo | | Corrigi tudo e preciso voltar a enviar hoje | A janela de 7 dias ainda não passou | Abra um chamado descrevendo a correção feita | ## Próximos passos [Seção intitulada “Próximos passos”](#próximos-passos) * [Resetar o cálculo da pontuação do domínio](/ajuda/smtp/resetar-o-calculo-da-pontuacao/) * [Validar o e-mail no seu formulário](/ajuda/smtp/validar-o-email-no-seu-formulario/) * [Acompanhar as métricas e a pontuação 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/) * [Impedir envios para um endereço (lista de supressão)](/ajuda/smtp/lista-de-supressao/) * [IP dedicado: quando ele resolve](/ajuda/smtp/ip-dedicado-quando-resolve/) # Acompanhar as métricas e a pontuação do domínio > Ver quanto foi enviado e entregue, e o que a pontuação do domínio diz sobre a reputação dos seus envios. As métricas mostram o volume e o resultado dos envios de cada domínio. A pontuação resume a saúde do domínio num número — e é o melhor aviso antecipado de que os provedores estão começando a desconfiar dos seus e-mails. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do SMTP, vá em **Envios → Métricas**. A lista mostra cada domínio com um gráfico resumido, a **Pontuação** e os **Alertas**. 2. Clique num domínio para ver o detalhe. Escolha **Data Início**, **Data Fim** e a **Granularidade** (por hora, dia ou mês) e clique em **Atualizar**. 3. Para ver a pontuação em detalhe, abra o domínio em **Infraestrutura → Domínios (SMTP)** e clique em **Histórico de pontuação**. Para os alertas, clique em **Ver alertas**. ## O que você vê [Seção intitulada “O que você vê”](#o-que-você-vê) | Onde | O que mostra | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Cards do detalhe | **Enviados**, **Entregues**, **Descartados**, **Bounces** (**Soft Bounce** e **Hard Bounce**) e **Banda** | | Gráficos | **Envios e Entregas**, **Bounces** e **Distribuição por Provedor** | | Pontuação | Os pontos perdidos por **Bounce**, **Spam Trap**, **Spam** e **DNS**, a evolução da pontuação e o histórico detalhado | | Qualidade (na lista de domínios) | A classificação do remetente: **Perfeito**, **Bom**, **Iniciante** ou **Ruim** | | Alertas de SPAM | Cada reclamação de spam recebida — veja abaixo | ## Alertas de SPAM [Seção intitulada “Alertas de SPAM”](#alertas-de-spam) Quando um destinatário marca a sua mensagem como spam, os provedores que oferecem esse retorno avisam a iPORTO. Cada aviso aparece em **Alertas de SPAM** — na página do domínio, em **Ver alertas** —, com o **Destinatário**, o **Remetente**, o **Assunto**, o **Message ID** e a data. No mesmo momento, o destinatário entra na [lista de supressão](/ajuda/smtp/lista-de-supressao/) do domínio e deixa de receber. Use o alerta para entender o que provocou a reclamação — o assunto e o remetente costumam dizer — e para refletir o descadastro no seu próprio sistema. ## O que a pontuação impede de entregar [Seção intitulada “O que a pontuação impede de entregar”](#o-que-a-pontuação-impede-de-entregar) Cada provedor de destino exige um mínimo. É isso que faz a queda da pontuação aparecer de uma vez: abaixo de 45, nada é enviado. | Sua pontuação | O que ainda é entregue | | ------------- | ------------------------------------------------------------------------- | | 95 ou mais | Todos os destinos | | 90 a 94 | Quase todos; bancos, órgãos federais e grandes multinacionais não recebem | | 85 a 89 | Grandes provedores de e-mail sim; órgãos públicos, Vivo, Claro e TIM não | | 80 a 84 | Gmail sim; Hotmail, Outlook, Yahoo, UOL, Terra e iCloud não | | 75 a 79 | Domínios corporativos `.com.br` sim; Gmail não | | 45 a 74 | Apenas destinos sem exigência própria de pontuação | | Abaixo de 45 | **Nenhum e-mail é enviado** | O card **Pontuação Atual**, na página do domínio, já traz essa frase pronta, junto da maior perda e do que a resolve. Se a sua pontuação caiu, o caminho está em [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/). ## Quando a pontuação é recalculada [Seção intitulada “Quando a pontuação é recalculada”](#quando-a-pontuação-é-recalculada) A cada 4 horas, sempre sobre os últimos 7 dias. **Cada domínio tem o seu horário** — a página do domínio mostra a última e a próxima verificação, e o botão **Verificar agora** antecipa a conta quando você acabou de corrigir algo. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) A pontuação vai de 0 a 100: começa em 100 e perde pontos quando o domínio acumula bounces, atinge armadilhas de spam, recebe reclamações de spam ou tem o DNS incompleto. A conta olha os últimos 7 dias, e os bounces só pesam a partir de 50 envios no período — um domínio com pouco volume não é penalizado por um ou dois erros. Cada causa aparece separada na página de pontuação — é por ali que você descobre o que corrigir: | Perda por | O que costuma resolver | | ------------- | ----------------------------------------------------------------------------------------------------- | | **Bounce** | Limpar a lista: tirar endereços inválidos e validar antes de enviar | | **Spam Trap** | Parar de enviar para listas antigas ou de origem desconhecida | | **Spam** | Enviar só para quem pediu, com descadastro visível e conteúdo esperado | | **DNS** | Publicar SPF, DKIM e DMARC — veja [Publicar os registros DNS](/ajuda/smtp/publicar-os-registros-dns/) | ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | --------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Muitos alertas de SPAM num envio | O público não esperava aquela mensagem — lista antiga, sem consentimento, ou assunto enganoso | Envie só para quem pediu, com descadastro visível; revise a origem da lista | | O domínio aparece em **Quarentena** | O envio do domínio está contido; nesse estado a edição fica bloqueada | Veja a pontuação e os alertas para entender a causa e abra um chamado | | A pontuação caiu de repente | Um envio para uma lista antiga gerou muitos bounces ou atingiu armadilhas de spam | Veja a maior perda no card de pontuação e siga [A pontuação do seu domínio caiu, e agora?](/ajuda/smtp/a-pontuacao-do-seu-dominio-caiu/) | | As métricas não mostram envios recentes | O período escolhido não cobre o envio | Ajuste **Data Início** e **Data Fim** e clique em **Atualizar** | ## 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 uma lista de e-mails](/ajuda/validador-de-email/validar-uma-lista/) # Adicionar um domínio de envio > Cadastrar o domínio da sua empresa no SMTP para enviar e-mails do seu sistema com ele. O domínio é o endereço de onde seus e-mails saem — o `suaempresa.com.br` de `contato@suaempresa.com.br`. É a primeira coisa a configurar no SMTP: as credenciais, os registros de DNS e o histórico ficam todos dentro dele. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Use um domínio **seu**. Domínios de e-mail gratuitos (Gmail, Outlook e afins) são recusados. * Você vai precisar, logo depois, de acesso ao DNS do domínio (no registro.br, Cloudflare, na sua hospedagem ou onde ele estiver) para publicar os registros. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. No painel do SMTP, vá em **Infraestrutura → Domínios (SMTP)** e clique em **Novo domínio**. 2. Em **Domínio**, digite só o domínio, sem `www` e sem `https://` — por exemplo, `suaempresa.com.br`. 3. Em **Tipo de envio**, escolha: * **Transacional** — mensagens que o seu sistema dispara uma a uma: confirmação de cadastro, recuperação de senha, pedido, nota fiscal. * **Marketing** — comunicação em volume para a sua base. 4. Em **Tipo de IP**, deixe **Compartilhado**, a menos que você tenha contratado um IP dedicado. 5. Clique em **Criar**. ## O que acontece depois [Seção intitulada “O que acontece depois”](#o-que-acontece-depois) * Você é levado à página do domínio, com as abas **Configurações**, **DNS**, **Credenciais** e **Instalação**. * Uma primeira credencial, **`no-reply@suaempresa.com.br`**, já é criada junto com o domínio. Você pode criar outras — veja [Criar uma credencial SMTP](/ajuda/smtp/criar-uma-credencial/). * Dá para começar a enviar em seguida. Mas, sem os registros de DNS publicados, os provedores (Gmail, Outlook…) têm motivo para desconfiar dos seus e-mails, e eles tendem a ir para o spam ou ser recusados. Publique os registros o quanto antes — veja [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/). ## Se der errado [Seção intitulada “Se der errado”](#se-der-errado) | Sintoma | Causa provável | O que fazer | | ------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- | | “Este domínio já está em uso.” | O domínio já está cadastrado — na sua conta ou em outra | Procure-o em **Domínios (SMTP)**; se não estiver lá, abra um chamado | | “Este domínio é bloqueado. Por favor, use um domínio próprio para envio.” | O domínio é de um provedor de e-mail gratuito ou público | Use o domínio da sua empresa | | “Este domínio esteve cadastrado em outra conta e precisa de revisão…” | O domínio foi usado antes em outra conta da iPORTO | Peça a liberação ao suporte por um chamado | | “Você não possui, disponível para uso, um plano de SMTP…” | Sua conta não tem plano de SMTP ativo | Confira a assinatura no portal do cliente, em **Financeiro → Assinatura** | | “Você atingiu o limite de domínios permitidos para o seu plano.” | O plano permite um número de domínios e todos estão em uso | Apague um domínio que não usa mais, ou mude de plano | | Erro ao escolher **Dedicado** em **Tipo de IP** | Você não tem IP dedicado disponível | Escolha **Compartilhado** | ## 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/) * [Conectar seu sistema ao servidor SMTP](/ajuda/smtp/conectar-seu-sistema/) # Ativar o descadastro em um clique > Os cabeçalhos List-Unsubscribe e List-Unsubscribe-Post, para o Gmail e o Yahoo mostrarem o botão de cancelar inscrição ao lado do remetente. Com dois cabeçalhos na mensagem, Gmail, Yahoo e outros provedores podem mostrar um botão **Cancelar inscrição** ao lado do remetente — e quem não quer mais receber sai por ali, em vez de marcar a mensagem como spam. Gmail e Yahoo pedem esse descadastro em um clique (RFC 8058) a quem envia mensagens de marketing em volume para eles. ## Antes de começar [Seção intitulada “Antes de começar”](#antes-de-começar) * Um domínio com os registros DNS publicados — sem eles a mensagem não sai assinada. Veja [Publicar os registros DNS do domínio](/ajuda/smtp/publicar-os-registros-dns/). * Um endereço `https` no seu sistema que descadastra o destinatário quando recebe um `POST`. ## Passo a passo [Seção intitulada “Passo a passo”](#passo-a-passo) 1. **Crie o endereço de descadastro no seu sistema.** Ele recebe um `POST` com o corpo `List-Unsubscribe=One-Click` e precisa: * identificar o destinatário pela própria URL — um código por destinatário, como `https://suaempresa.com.br/sair/abc123`, e não o e-mail aberto na URL; * descadastrar na hora, sem login, sem página de confirmação e sem redirecionar; * responder `200`. Quem abre o mesmo endereço no navegador chega por `GET`: aí mostre uma página com o botão de confirmar. Só o `POST` descadastra direto. 2. **Inclua os dois cabeçalhos em cada mensagem**, com a URL daquele destinatário: ```text List-Unsubscribe: List-Unsubscribe-Post: List-Unsubscribe=One-Click ``` O valor de `List-Unsubscribe-Post` é sempre esse, exatamente assim. 3. **Faça um envio de teste para uma caixa do Gmail** e abra a mensagem em **Mais (⋮) → Mostrar original**. Confira três coisas: * os dois cabeçalhos aparecem como você enviou; * no `DKIM-Signature`, o campo `h=` traz `List-Unsubscribe` e `List-Unsubscribe-Post`; * o resultado do DKIM é `PASS`. ## Exemplos [Seção intitulada “Exemplos”](#exemplos) Os mesmos envios de [Conectar seu sistema ao servidor SMTP](/ajuda/smtp/conectar-seu-sistema/), com os dois cabeçalhos. **PHP (PHPMailer)** ```php $mail->addCustomHeader('List-Unsubscribe', ''); $mail->addCustomHeader('List-Unsubscribe-Post', 'List-Unsubscribe=One-Click'); ``` **Node.js (Nodemailer)** ```js await transporter.sendMail({ from: '"Sua Empresa" ', to: 'cliente@exemplo.com', subject: 'Novidades da semana', html: '

Olá! Confira as novidades.

', headers: { 'List-Unsubscribe': '', 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click', }, }); ``` **Python (smtplib)** ```python msg["List-Unsubscribe"] = "" 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/) |