2026 Supabase Auth: não recebe emails de teste? O que verificar no desenvolvimento, QA e antes do lançamento

Na configuração local documentada pelo Supabase, emails de Auth são capturados e podem ser consultados na interface local do Inbucket, em http://localhost:54324; essa captura não comprova entrega externa (documentação de testes locais do Supabase). A ação recomendada nesta semana é identificar primeiro o ambiente: no desenvolvimento local, examine a mensagem capturada; em um projeto hospedado, confira SMTP, destinatário autorizado e logs de Auth. Se a aprovação depende de uma caixa externa real, faça o teste em uma implantação de pré-produção do seu próprio produto.

Este guia é para quem implementa confirmação de cadastro ou login por email com Supabase Auth e precisa separar geração da mensagem, envio e recebimento.
Também atende QA que precisa registrar evidências reproduzíveis, sem confundir uma captura local com uma entrega real.
Quem prepara um lançamento encontrará critérios para decidir quando o teste local basta e quando é preciso validar o caminho externo.

Desenvolvimento: captura local não é envio externo

Ao trabalhar localmente, o primeiro ponto é saber o que o ambiente está fazendo com a mensagem. A configuração de desenvolvimento do Supabase captura emails de Auth em uma caixa local. Portanto, não espere que uma mensagem de confirmação apareça automaticamente no endereço pessoal usado como destinatário. Consulte a interface do Inbucket indicada na documentação de testes locais, em vez de repetir o cadastro e presumir que o envio falhou.

Essa distinção evita um diagnóstico errado: a aplicação pode ter acionado o fluxo e gerado uma mensagem, embora nenhum serviço externo tenha recebido uma solicitação. A caixa local ajuda a inspecionar o conteúdo e o comportamento da aplicação; ela não simula, por si só, toda a cadeia entre o projeto, um servidor SMTP e a caixa de entrada do usuário.

Para depurar Supabase Auth local, siga uma ordem que preserve evidências:

• Confirme que o processo local do Supabase está em execução e que a aplicação aponta para o projeto local, não para o projeto hospedado.
• Acione o fluxo que deseja testar, como cadastro ou solicitação de confirmação, usando dados de teste do seu próprio produto.
• Abra a interface de captura local e procure a mensagem correspondente ao endereço utilizado.
• Se a mensagem estiver lá, inspecione assunto, corpo, variáveis do modelo e destino do link.
• Se não estiver, compare a ação executada com o fluxo de autenticação configurado e examine os logs antes de repetir a solicitação.

O processo local, os serviços e as opções relevantes podem ser ajustados pela configuração do Supabase. A documentação oficial de configuração local ajuda a verificar se a execução está usando os valores esperados. Para personalizar modelos usados em desenvolvimento, consulte também as instruções de modelos de email no ambiente local.

Exemplo de diagnóstico: um desenvolvedor altera o texto da confirmação, cadastra um usuário de teste e não vê nada na caixa pessoal. Se o projeto ativo é local, a primeira ação útil não é mudar DNS nem trocar de destinatário: é abrir a caixa de captura e verificar se a mensagem foi gerada. Se estiver ausente, os logs e a configuração local ajudam a encontrar o ponto anterior ao envio.

QA: defina se o teste é de conteúdo, de fluxo ou de recebimento

QA precisa nomear o objetivo do caso antes de declarar aprovação. “O email funciona” mistura verificações diferentes e deixa uma lacuna: um teste pode validar o texto e o link sem provar que um provedor externo entregará a mensagem.

• Inspeção do conteúdo: confira assunto, texto, variáveis e link no email capturado localmente. Isso é adequado para revisar alterações de modelo sem depender de uma caixa externa.
• Validação do fluxo: acione a confirmação e verifique se o link leva ao comportamento esperado da aplicação. A mensagem pode ser capturada localmente; a validação do destino também depende da configuração do projeto e do tratamento feito pelo aplicativo.
• Recebimento externo: confirme que uma mensagem foi enviada a uma caixa de teste fora do ambiente local. Para essa evidência, use um projeto hospedado e uma configuração de envio compatível com os destinatários do teste.

Ao registrar um defeito, anote ambiente, projeto usado, ação que iniciou o envio, endereço de destino e resultado observável. Guarde o horário da tentativa, o trecho relevante do log e, quando aplicável, a mensagem capturada ou o resultado da caixa externa. Sem essa separação, outra pessoa pode repetir um teste em ambiente diferente e concluir que o problema desapareceu, quando na verdade mudou o caminho de envio.

Há também uma diferença importante entre um endereço de teste e um endereço destinado à recuperação de uma conta. Para cenários descartáveis do seu produto, um endereço de email adequado ao tipo de teste pode evitar expor uma caixa pessoal e reduzir o acúmulo de mensagens de desenvolvimento. Para contas que precisam permanecer acessíveis, use um endereço controlado pela equipe e mantenha acesso consistente durante todo o ciclo de teste.

Manutenção do projeto: restrição de envio ou falha de entrega?

Em um projeto hospedado, não assuma que o serviço padrão enviará para qualquer destinatário. A documentação de SMTP para Supabase Auth descreve limitações do serviço padrão, incluindo limite de 2 emails por hora e restrição de envio a endereços associados à equipe do projeto. Como essas condições podem mudar, confirme sempre a documentação vigente antes de interpretar uma recusa.

Se o destinatário de teste não estiver dentro do escopo permitido, o resultado pode parecer uma falha de entrega, embora a tentativa tenha sido recusada antes de chegar a um serviço externo. Para testar caixas externas em um fluxo do seu próprio produto, verifique se o projeto está configurado com um servidor SMTP apropriado para essa finalidade e se os dados dessa configuração correspondem ao ambiente correto.

Depois, examine os logs de Auth. O objetivo é descobrir em que etapa a tentativa parou: a aplicação não iniciou o fluxo, o projeto não aceitou a solicitação, houve uma falha ao transferir a mensagem ao SMTP ou o serviço de envio aceitou a mensagem e o problema passou a ser de entrega ou localização. A referência de códigos de erro de Auth ajuda a interpretar os erros registrados; o guia oficial para investigar emails de Auth não recebidos orienta a separar essas hipóteses.

Não transforme um erro isolado em regra geral. Uma recusa de destinatário em um projeto não demonstra que todos os projetos têm a mesma configuração; uma mensagem aceita pelo serviço também não garante que a caixa de entrada a exibirá. Registre o erro exato, a configuração vigente e o endereço usado, preservando dados pessoais desnecessários fora dos registros.

Modelos e redirecionamentos: mensagem gerada não significa link aprovado

Quem altera o conteúdo precisa conferir as variáveis utilizadas pelo modelo e verificar se o link corresponde ao fluxo pretendido. Um email pode estar presente na caixa de captura e ainda conter uma variável incorreta, um endereço incompleto ou um destino que a aplicação não trata. Portanto, “a mensagem apareceu” responde apenas a uma parte do teste.

Use a documentação de modelos de email do Supabase Auth para confirmar como os modelos são configurados e quais informações podem ser inseridas neles. Depois, verifique as URLs de redirecionamento permitidas na documentação de redirecionamentos do Supabase Auth. A allowlist do projeto e a lógica da aplicação são verificações separadas: uma URL permitida não garante que a tela de destino processe o estado de confirmação corretamente.

No teste, siga o link a partir da mensagem e observe o resultado final. Confira se a aplicação abre o ambiente certo, se conclui a confirmação e se apresenta um estado compreensível quando o link não pode ser usado. Evite copiar para relatórios públicos links de confirmação que ainda possam ser válidos; eles podem conter informações sensíveis ou conceder acesso a uma ação de autenticação.

Uma mensagem visível na captura local prova que há algo a inspecionar. Ela não prova envio externo, autorização do destinatário, entrega na caixa de entrada nem conclusão correta do redirecionamento.

Lista de decisão para classificar a falha antes de repetir o teste

Use esta lista antes de pedir um novo cadastro ou de alterar a configuração. Cada item deve resultar em uma evidência verificável.

• [ ] Identifique se a tentativa ocorreu no ambiente local ou em um projeto hospedado.
• [ ] No ambiente local, consulte a interface de captura indicada pelo Supabase e confirme se a mensagem foi gerada.
• [ ] Registre qual ação iniciou o fluxo: cadastro, confirmação ou outra operação de Auth.
• [ ] Inspecione o modelo e o link, sem tratar a presença do email como prova de recebimento externo.
• [ ] Em projeto hospedado, confira se há SMTP personalizado e se o destinatário é aceito pela configuração atual.
• [ ] Consulte os logs de Auth e guarde o erro ou o evento associado à tentativa.
• [ ] Se o serviço aceitou a mensagem, procure a evidência na caixa externa e investigue o recebimento sem atribuir automaticamente a causa ao Supabase.
• [ ] Se o link falhou, verifique tanto as URLs permitidas no projeto quanto o tratamento da rota na aplicação.
• [ ] Repita o teste apenas depois de registrar a mudança feita e manter o mesmo ambiente e objetivo de validação.

A leitura rápida dos sintomas fica assim:

• A caixa local não mostra mensagem: confirme o projeto ativo, a ação acionada e os logs; ainda não é uma questão de entrega externa.
• O projeto recusa o envio: verifique o SMTP e as regras atuais para o destinatário antes de testar outra caixa.
• O serviço aceitou, mas a caixa não mostra email: investigue o caminho após a transferência, usando os registros disponíveis do serviço e da caixa de teste.
• O link abre o destino errado ou falha: examine o conteúdo do modelo, a allowlist de redirecionamentos e o processamento da aplicação.

FAQ: dúvidas comuns durante testes de Auth

Onde consultar a confirmação criada no desenvolvimento local?

No modo local descrito pelo Supabase, a mensagem é capturada na interface do Inbucket, em vez de seguir diretamente para uma caixa externa. Use essa interface para examinar o email gerado, incluindo o conteúdo e o link. Se a intenção é verificar recebimento real, será necessário testar em um ambiente de envio apropriado; a captura local não substitui essa verificação.

O email do Supabase Auth não chegou à caixa real: o que verificar primeiro?

Confirme se a aplicação está apontando para o ambiente local ou para um projeto hospedado. Em modo local, a captura explica por que não há entrega externa. No projeto hospedado, verifique SMTP, as permissões ou limitações aplicáveis ao destinatário e os logs de Auth. Se o serviço de envio aceitou a mensagem, só então investigue o caminho até a caixa externa.

Como resolver uma mensagem de destinatário não autorizado?

Confira a configuração de envio e compare o destinatário com as limitações atuais do serviço padrão documentadas pelo Supabase. Se o teste exige uma caixa externa não permitida, planeje o uso de SMTP adequado no ambiente de teste do seu produto. Depois de alterar a configuração, confirme o resultado nos logs. Não confunda uma recusa do projeto com uma falha do endereço de recebimento.

Como saber se o serviço de email recebeu a solicitação?

Examine os logs de Auth para encontrar o evento da tentativa e identificar se houve erro durante a transferência. A captura local demonstra geração, não entrega a um SMTP externo. Em um projeto hospedado, um registro de envio aceito pelo serviço também não comprova que a mensagem apareceu na caixa de entrada; mantenha essa distinção no resultado de QA.

Lançamento: quando exigir uma caixa externa real

Antes de publicar, determine qual promessa o teste precisa sustentar. Se a equipe só precisa conferir o modelo, a captura local pode bastar. Se precisa aprovar o caminho de confirmação, teste também o link e o redirecionamento. Se a aprovação exige provar que um usuário recebe o email em uma caixa externa, faça uma validação real em pré-produção, com o SMTP e os destinatários adequados.

Não generalize o resultado de uma tentativa. Um email recebido demonstra que aquele caminho funcionou naquele contexto; não estabelece uma taxa de entrega para todos os provedores, domínios ou destinatários. Registre a configuração de envio, o ambiente, o resultado observado e os erros encontrados, para que a equipe saiba exatamente o que foi validado.

Para cenários de demonstração ou QA com dados pessoais, prefira endereços controlados e evite colocar informações reais de usuários em ambientes não produtivos. Nossa orientação sobre privacidade no uso de email ajuda a pensar nessa separação. Se a equipe precisa receber mensagens de teste em uma caixa que continuará ativa, considere também os limites e a gestão de um encaminhamento, em vez de usar um endereço descartável como única forma de recuperação.

Quando a validação envolve apenas um cadastro temporário, uma confirmação ou uma mensagem de teste do seu próprio produto, um endereço temporário pode ser uma opção simples para não expor a caixa principal nem misturar notificações de QA com mensagens de trabalho. O SendTmp permite abrir uma caixa temporária sem cadastro e usá-la de imediato; isso é útil para observar o recebimento, mas não substitui a checagem de SMTP, logs e redirecionamentos. Para contas importantes, que exigem recuperação futura ou comunicação contínua, mantenha um endereço duradouro sob controle da equipe.