Tovanix
Tovanix

Usar a API de agregação SMTP

Reúna várias contas SMTP suas em uma única saída de envio, com a alternância feita pela plataforma:

  • O plano gratuito é ativado automaticamente no primeiro uso; cota, recursos disponíveis e limites dependem do plano, e para trocar de plano use “Mudar de plano” — o tempo não usado é abatido pelo preço original
  • Adicione primeiro uma conta em Contas SMTP e depois crie uma chave em Chaves API; criar e redefinir exigem verificar a identidade, e a chave aparece uma única vez
  • Três formas de enviar: composição online, campanhas e chamadas de API; as campanhas mesclam e removem duplicatas e ignoram a lista de cancelamento de inscrição
  • Uma conta SMTP que falha 3 vezes seguidas por problemas da própria conta passa para “Erro” e é restaurada automaticamente quando a verificação da plataforma passa
  • Erros comuns: 400 se resolve pela message (cota esgotada, destinatário informado como devolução etc.), 401 é chave inválida, 403 é conta restrita e 429 é excesso de requisições

O que este serviço faz

A API de agregação SMTP reúne várias contas de envio SMTP suas em uma única saída: o seu sistema se integra à plataforma uma única vez, e a plataforma alterna o envio entre essas contas. Você pode enviar direto pelo console ou, pela API, a partir do seu próprio sistema.

  • Serve para e-mails transacionais, como códigos de cadastro e avisos de pedidos, e também para envios em massa a grupos de contatos.
  • No primeiro uso, o plano gratuito é ativado automaticamente. Depois de adicionar uma conta SMTP e criar uma chave de API, você já pode enviar; troque de plano quando precisar de mais cota ou de mais recursos.
  • Fica em API de agregação SMTP, no console, com as páginas divididas em três grupos: Envio, Integrações e Configuração.

Alguns termos primeiro

Esta seção tem muitas páginas. Entender os conceitos primeiro ajuda a evitar acessar a página errada.

  • Plano — Define quantos e-mails você pode enviar por dia e por mês, quais recursos pode usar (modelos de e-mail, contatos, campanhas, Webhook) e o limite de cada um; os cartões da página Assinar detalham item por item. No primeiro uso, o plano gratuito é ativado automaticamente; quando um plano pago vence, a conta volta ao plano gratuito.
  • Conta SMTP — Sua própria conta de envio SMTP (de um provedor de e-mail ou de um servidor próprio); a plataforma não fornece canal de envio. Você pode adicionar várias, cada uma com prioridade e limite diário de envio, e a plataforma alterna o envio entre elas.
  • Chave de API — A credencial que o seu sistema usa para chamar a API de envio. A chave de API responde por “quem está chamando”; a conta SMTP, por “de qual caixa de e-mail o envio sai”.
  • Domínio de envio — O domínio depois do @ no seu endereço de envio. Na página Domínios de envio, verifique os registros SPF, DKIM e DMARC; com eles completos, os e-mails chegam com mais facilidade à caixa de entrada.
  • Lista de cancelamento de inscrição — Endereços que se descadastraram pelo link de cancelamento de inscrição, além dos que o seu sistema informou pela API como devolução ou reclamação. A plataforma ignora esses endereços automaticamente, sem manutenção manual.

Envie o primeiro e-mail

  • Confira o plano: No primeiro acesso, o plano gratuito é ativado automaticamente. Em API de agregação SMTP → Assinar, você vê o plano atual e a cota de cada plano; assine um nível acima quando precisar de mais cota ou de mais recursos.
  • Adicione uma conta SMTP: Na página Contas SMTP, clique em “Adicionar conta” e informe o servidor, a porta, o usuário, a senha e o e-mail de envio. Quantas contas você pode adicionar depende do plano; com várias, a plataforma alterna o envio automaticamente.
  • Crie uma chave de API: Na página Chaves API, clique em “Criar chave de API”. Criar e redefinir exigem verificar sua identidade antes: com a verificação em duas etapas ativada, informe o código dinâmico; sem ela, use um código enviado por e-mail. Depois de verificar uma vez, você não precisa repetir por 10 minutos nesta sessão. A chave aparece uma única vez — copie e guarde na hora; cada conta pode ter até 50 chaves.
  • Envie um e-mail de teste: Na página Contas SMTP, clique em “Testar” para testar a conexão ou enviar um e-mail de teste para você mesmo. E-mails de teste não consomem a cota de envio, então teste quantas vezes quiser.

Se você já tem um plano pago, troque de plano na página Assinar escolhendo outro nível e clicando em “Mudar de plano”; a troca vale na hora. O tempo não usado do plano atual é abatido pelo preço original, e você paga só a diferença; se o abatimento passar do preço do novo plano, o excedente vira tempo adicional, sem devolução ao saldo. A cota já usada no mês passa para o novo plano.

Excluir uma chave de API faz falhar todas as requisições que ainda a usam; redefinir também invalida a chave original na hora. Para uma chave em uso em produção, configure a nova antes de mexer na antiga.

Três formas de enviar

Uma cota, três caminhos — escolha conforme a situação:

  • Escrever online — Escreva e envie pelo console. Ideal para avisos únicos e reenvios manuais.
  • Campanha — Escolha um modelo e grupos de contatos para enviar em massa, com controle de velocidade, rastreamento e agendamento. O sistema reúne, elimina duplicatas e exclui quem cancelou a inscrição.
  • Chamada de API — Seu sistema chama diretamente o endpoint. Uma requisição pode ter vários destinatários, cada um com suas próprias variáveis de modelo.

Modelos e variáveis

Coloque o conteúdo em um modelo e envie só variáveis na chamada; assim, conteúdo e código não ficam misturados.

  • Modelos são mantidos na página Modelos e referenciados por identificador no envio; a plataforma faz as substituições.
  • A plataforma gera uma versão em texto simples a partir do HTML, mantendo a leitura onde HTML não funciona.

Contatos e cancelamentos de inscrição

A página Contatos guarda endereços e grupos, com importação e exportação em CSV; nas campanhas, você escolhe os destinatários por grupo.

  • Selecionar vários grupos reúne e elimina duplicatas, evitando que alguém receba o mesmo e-mail duas vezes.
  • Na importação de CSV, endereços que cancelaram a inscrição são ignorados automaticamente.
  • O link de cancelamento leva a uma página de confirmação; confirmar adiciona o endereço à lista e marca o contato.

A lista de cancelamento de inscrição vale automaticamente. Endereços informados como devolução ou reclamação não recebem mais nenhum e-mail; endereços que se descadastraram pelo link só são ignorados em campanhas e envios em lote — e-mails individuais, como códigos de verificação, continuam sendo enviados normalmente.

Domínios de envio

Na página Domínios de envio, adicione o domínio que você usa para enviar (a parte depois do @ no e-mail de envio) e, se quiser, informe também o seletor DKIM (fornecido pelo seu provedor de e-mail). A plataforma verifica os registros SPF, DKIM e DMARC e mostra os registros DNS recomendados e o nível de integridade. Com os registros completos, os e-mails chegam com mais facilidade à caixa de entrada. Esta etapa não é obrigatória para enviar; a quantidade de domínios que você pode adicionar depende do plano.

Webhooks e eventos

Para saber o resultado de cada mensagem, configure um webhook; a plataforma chamará seu serviço com eventos de entrega.

  • Eventos cobrem o processo e o resultado da entrega, além de cancelamentos de inscrição e conclusão de campanhas.
  • Callbacks são assinados, e seu servidor deve verificar a assinatura antes de confiar — essa etapa é a fronteira de segurança, não a ignore.

Erros comuns e soluções

Quando uma chamada falhar, veja primeiro o código de status HTTP e a message da resposta e depois siga a tabela abaixo.

  • Retorno 400 — Requisição recusada: cota esgotada, destinatário já informado como devolução ou reclamação, nenhuma conta SMTP disponível, parâmetros incorretos etc. — Siga o que diz a message. Se a cota acabou, espere o reinício (a cota diária reinicia à 0h no fuso horário da sua conta, que pode ser alterado nas configurações da conta; a mensal, no início de cada mês) ou mude para um plano maior; se o aviso for de que não há conta SMTP disponível, confira o status na página Contas SMTP.
  • Retorno 401 — A requisição não trouxe chave de API, ou a chave é inválida, foi desativada, excluída ou redefinida — Confira o status na página Chaves API e troque a chave no seu sistema pela que está válida.
  • Retorno 403 — A conta está congelada ou restrita — Uma conta restrita (código de erro 4031) ainda pode chamar as APIs de consulta, mas os envios são recusados. Fale com o suporte.
  • Retorno 429 — Requisições demais: no máximo 20 por segundo por chave de API e 60 por segundo no total por conta — Aguarde o tempo indicado no cabeçalho Retry-After e envie de novo. Para enviar a muitas pessoas, use uma requisição com vários destinatários ou uma campanha, em vez de chamadas rápidas, uma por e-mail.
  • O e-mail é enviado, mas cai no spam — Domínio não configurado ou conteúdo acionando filtros — Na página Domínios de envio, verifique SPF, DKIM e DMARC, complete os registros DNS recomendados e depois revise o conteúdo; antes de uma campanha real, você pode conferir tudo com a Simulação de entrega.

Se uma conta SMTP falhar 3 vezes seguidas por problemas da própria conta, como falha de login ou impossibilidade de conectar ao servidor, o status muda para “Erro” e ela deixa de participar da alternância. A plataforma verifica periodicamente e a restaura quando a verificação passa; você também pode testar a conexão ou enviar um e-mail de teste na página Contas SMTP — se der certo, ela volta —, corrigir os dados de conexão ou ativá-la manualmente.

Perguntas frequentes

Já configurei tudo. Por que ainda não consigo enviar?

Confira nesta ordem: se há alguma conta ativa em Contas SMTP (contas com status “Erro” não enviam); se a chave de API usada é a que está válida; se a cota do dia ou do mês acabou. A message retornada pela API informa o motivo exato.

E-mails de teste consomem cota?

Não. Os envios de teste da página Contas SMTP não contam na cota de envio, então teste à vontade durante a configuração.

O que acontece quando um plano pago vence?

Quando ele vence, a conta volta à cota e aos recursos do plano gratuito. Para continuar, clique em “Renovar” na página Assinar antes do vencimento ou assine de novo depois.

Páginas relacionadas: Central de Ajuda · Guias e perguntas frequentes · API de agregação SMTP · Documentação da API

Carregando…