Resolução de problemas em e-mail transacional

Este artigo aborda os problemas mais comuns com o e-mail transacional do Flexmail — erros de autenticação, problemas de entregabilidade e falhas na API ou SMTP — e o que fazer em cada caso.

Erros de autenticação e configuração

A API devolve um erro 401 Unauthorized

O ID da conta ou o token de acesso pessoal está errado. Verifique ambos com cuidado:

  • O nome de utilizador é o ID numérico da conta, não o endereço de e-mail.
  • A palavra-passe é um token de acesso pessoal criado em Definições > API > Tokens de acesso pessoal, não a palavra-passe de início de sessão no Flexmail.
  • Certifique-se de que o token foi copiado na íntegra, sem espaços ou quebras de linha no final.
  • Em caso de dúvida, crie um novo token e tente novamente.

A ligação SMTP falha ou excede o tempo limite

Verifique o seguinte:

  • Está a usar o host submission.flexmail.eu, porta 587, com STARTTLS.
  • O servidor ou ambiente de alojamento permite ligações de saída na porta 587. Alguns fornecedores de alojamento partilhado bloqueiam esta porta — contacte o seu fornecedor para confirmar.
  • As credenciais SMTP são o nome de utilizador e a palavra-passe fornecidos pelo Flexmail quando ativou o acesso SMTP. Estas são separadas do ID da conta e do token de acesso pessoal, que são usados apenas para a API HTTP.
  • O endereço de remetente está verificado no Flexmail.

Endereço de remetente não verificado

Se tentar enviar a partir de um endereço que não está verificado no Flexmail, o envio será rejeitado. Vá a Definições > Adicionar ou remover remetentes, adicione o endereço e clique na ligação de verificação no e-mail que o Flexmail envia.

Problemas de entregabilidade

Os e-mails vão para spam

O encaminhamento para spam em e-mail transacional é quase sempre causado por uma de três situações:

  • A autenticação de e-mail não está configurada ou está incorreta. Verifique se os registos SPF, DKIM e DMARC estão implementados para o domínio de envio. Mesmo um registo em falta ou mal configurado pode causar encaminhamento para spam. As instruções de configuração estão na documentação da API em email-api.flexmail.eu/documentation, na secção Email authentication.
  • A reputação do remetente é baixa. Se o domínio ou IP tiver historial de queixas de spam ou taxas de bounce elevadas — em qualquer plataforma de envio, não apenas no Flexmail — os fornecedores de caixa de entrada podem encaminhar o e-mail para spam. Consulte "Compreender a reputação do remetente" para saber como avaliar e melhorar a reputação.
  • O conteúdo aciona filtros de spam. Determinados padrões na linha de assunto, ligações em excesso ou e-mails com muitas imagens e pouco texto podem acionar filtros de spam. Teste os e-mails transacionais com uma ferramenta como o Mail-Tester (mail-tester.com) para identificar problemas ao nível do conteúdo.

Os e-mails não chegam de todo

Se a API devolve uma resposta de sucesso mas o e-mail não chega:

  • Verifique os eventos de webhook (se configurados) — um evento de bounce pouco depois do envio indica uma falha de entrega.
  • Verifique se o endereço do destinatário existe e está escrito corretamente.
  • Peça ao destinatário para verificar a pasta de spam.
  • Verifique se o domínio do destinatário tem uma política DMARC rigorosa — sem DKIM corretamente configurado, os e-mails podem ser silenciosamente rejeitados.
  • Alguns sistemas de e-mail corporativo rejeitam e-mails de remetentes novos ou com baixa reputação. Tente enviar para um endereço pessoal Gmail ou Outlook para excluir filtragem do lado do destinatário.

Taxa de bounce elevada

Uma taxa de bounce elevada em e-mail transacional significa geralmente que está a enviar para endereços que não existem ou já não estão ativos. Verifique o processo de recolha de endereços:

  • Está a validar o formato do endereço de e-mail no momento da inserção?
  • Está a enviar um e-mail de confirmação ou verificação antes de confiar num novo endereço?
  • Está a remover prontamente os endereços com hard bounce do sistema?

Importante

Continuar a enviar para endereços com hard bounce danifica a reputação do remetente a cada envio. Configure o tratamento de webhooks para eventos de bounce e suprima esses endereços no sistema imediatamente.

Erros de API e integração

A API devolve um erro 422 ou 400

Estes erros indicam um problema com o pedido — um campo obrigatório em falta, um valor de parâmetro inválido ou um corpo de pedido malformado. Verifique a mensagem de erro no corpo da resposta para mais detalhes. A documentação da API em email-api.flexmail.eu/documentation lista todos os parâmetros obrigatórios e opcionais para cada endpoint.

A API devolve um erro 429 Too Many Requests

Atingiu um limite de taxa. A documentação da API especifica os limites de taxa para o nível de subscrição. Adicione lógica de retentar com recuo exponencial à integração para gerir isto de forma adequada.

As variáveis do modelo não estão a ser substituídas

Se o texto do marcador aparecer literalmente no e-mail entregue:

  • Verifique se está a passar os valores das variáveis corretamente no pedido à API. Consulte a secção Templates da documentação da API para a estrutura exata dos parâmetros.
  • Verifique se a sintaxe do marcador no modelo corresponde exatamente ao que a API espera.
  • Certifique-se de que está a referenciar o ID de modelo correto na chamada à API.

Os webhooks não estão a chegar

Se o endpoint de webhook não está a receber eventos:

  • Confirme que o endpoint está acessível publicamente via HTTPS.
  • Verifique se o endpoint devolve uma resposta 2xx rapidamente — um endpoint lento ou sem resposta fará com que o Flexmail considere a entrega como falhada.
  • Verifique os registos do servidor para pedidos POST recebidos, para excluir problemas de roteamento ou firewall.
  • Verifique se o URL do endpoint de webhook está registado corretamente na API.

Obter ajuda

Se seguiu os passos acima e o problema persiste, contacte a equipa de suporte do Flexmail em support@flexmail.eu. Inclua na mensagem as seguintes informações para agilizar o diagnóstico:

  • O ID da mensagem de um envio com falha (da resposta da API ou dos registos).
  • O endereço de e-mail do destinatário com que testou.
  • A mensagem de erro ou o corpo da resposta da API, se aplicável.
  • O resultado de uma ferramenta de verificação de autenticação de e-mail, como MXToolbox ou Mail-Tester.

Próximos passos

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.