Como personalizar e-mails de confirmação e redefinição de senha no Supabase Auth

Quem acaba de criar uma conta precisa reconhecer a aplicação e entender como confirmar o cadastro. Quem esqueceu a senha precisa de outra mensagem, com uma ação igualmente clara. Você pode criar esses dois layouts no Mailvex e transferir o HTML para os templates correspondentes do Supabase Auth.

Este roteiro parte de uma aplicação que usa um projeto hospedado do Supabase com confirmação de cadastro e recuperação de senha já funcionando. Confira ambos os fluxos no projeto de testes antes da mudança. Use SMTP personalizado configurado e os templates processados pelo painel, sem um Send Email hook ativo controlando a renderização. O objetivo é mudar a apresentação e preservar o comportamento de autenticação existente.

1. Salve o que funciona antes de editar

Em Authentication > Email Templates, abra Confirm sign up e salve separadamente o Subject e todo o código de Body. Faça outra cópia para Reset password. Em cada fonte, registre a expressão exata do href da ação principal. Copie do template, nunca de uma mensagem recebida: o link recebido pode conter um token real de uso único.

O caminho simples abaixo vale quando cada template já utiliza {{ .ConfirmationURL }}. O Supabase fornece a ação correspondente a cada tipo de e-mail. Se o código usa callback próprio, SSR/PKCE, .TokenHash, OTP com .Token ou condições Go, preserve sua lógica e peça revisão ao desenvolvedor antes de adaptar o layout. Não troque esse fluxo pelo padrão apenas por estar redesenhando a mensagem.

Se houver Send Email hook, o renderer desse fluxo controla os e-mails; não desative um hook em funcionamento para seguir o tutorial. Instalações locais ou autogerenciadas usam outra configuração. Se o editor estiver somente para leitura, confira os requisitos de envio e acesso do projeto, sem presumir que contratar Pro seja sempre a solução.

O SMTP integrado tem destinatários restritos à equipe e limites baixos sujeitos a mudança; não é a base deste exemplo de produção. Confirme o SMTP personalizado no ambiente de testes e use contas e caixas de e-mail sob seu controle. Se a recuperação já estiver quebrada, mudar o template não corrige o backend.

2. Crie duas mensagens, com uma ação clara em cada uma

No Mailvex, use uma conta com e-mail confirmado e exportações disponíveis. Escolha Usar modelo no catálogo ou Usar este modelo nos detalhes. Prefira uma coluna, logotipo opcional, título legível, texto curto e um botão principal. A mensagem precisa continuar compreensível quando as imagens estiverem bloqueadas.

Confirmação de cadastro

Redefinição de senha

Mantenha a segunda versão em um projeto separado, com a mesma identidade visual e conteúdo próprio. Não coloque campos para digitar senha dentro do e-mail. O título e o preheader do Mailvex não alteram automaticamente o Subject do Supabase: você preencherá esse campo em cada template.

3. Prepare o link temporário e os elementos do design

Use o bloco padrão Botão centralizado e coloque o endereço abaixo somente nessa ação de autenticação. Ele é um marcador reservado que não funciona como destino; nunca publique a versão final com esse endereço. Não o use em imagens, links de suporte ou outros elementos.

https://example.invalid/MAILVEX_AUTH_ACTION

• No painel esquerdo, abra Ajustes > Tags UTM e desligue Adicionar UTM a todos os links.
• Depois disso, digite novamente o endereço temporário exato no botão, sem parâmetros, fragmentos ou espaços. Desligar UTM não remove parâmetros já gravados no link.
• No botão e nos blocos que o contêm, abra Visibilidade e mantenha Ocultar no mobile e Ocultar no desktop desligados. A ação precisa aparecer nas duas telas.
• No cabeçalho, abra Link «Ver no navegador» e desligue Mostrar link. Remova também links manuais para prévias hospedadas que tenham sido incluídos no conteúdo.
• Remova variáveis de demonstração sem uso. Nos blocos com Condição de exibição (ESP), desligue Mostrar por condição quando a regra não fizer parte do design estático.
• Confira preheader, rodapé, texto alternativo das imagens e leitura na tela estreita. Preserve a assinatura exigida pelo plano.

A prévia hospedada do Mailvex não recebe a substituição posterior do Supabase. Desligar o link do cabeçalho não prova que versões antigas tenham sido apagadas. Neste processo, o projeto recebe apenas o marcador: não cole tokens nem links reais de autenticação no editor, em capturas públicas ou em exemplos compartilhados.

Use imagens públicas, acessíveis sem login. O modo Mailvex preserva URLs hospedadas; arquivos externos podem continuar em outros hosts. O modo Próprio não faz upload dos arquivos para o seu servidor. Mantenha disponíveis os recursos usados em mensagens que as pessoas ainda podem abrir.

4. Exporte e adapte cada HTML separadamente

Abra Exportar HTML e mantenha mailvex em Formato de variáveis (ESP). Use Copiar HTML uma vez por variante: são dois projetos e duas exportações distintas. Baixar HTML é uma alternativa, não uma etapa adicional obrigatória. Confira sua cota antes de repetir a operação.

Salve o código completo em um arquivo .html usando um editor de texto ou código. Preserve uma cópia exportada sem alterações e outra para adaptação. Não separe body e CSS nem utilize um editor de texto formatado que possa alterar aspas. Mailvex não conecta o projeto ao Supabase nem gera o token.

Para o fluxo padrão já confirmado no backup daquele template, encontre o endereço temporário completo e substitua todas as suas ocorrências por esta expressão:

{{ .ConfirmationURL }}

O href resultante deve ficar assim no código-fonte:

href="{{ .ConfirmationURL }}"

Um botão visível pode gerar um href comum e outro em uma representação VML para Outlook. A quantidade varia; por isso, substitua todas as ocorrências do marcador exclusivo, não apenas a primeira. Não substitua todos os hrefs do documento: os destinos de suporte e as URLs das imagens continuam próprios.

O processamento do template pode remover comentários condicionais e sua versão VML, deixando o link HTML comum. A quantidade de hrefs pode diminuir após a renderização. Use o bloco padrão visível e confira a ação recebida; não remova estilos globalmente nem presuma aparência idêntica em todos os clientes.

Busque MAILVEX_AUTH_ACTION no arquivo adaptado: não deve restar nenhuma ocorrência. Confira que os destinos usam a expressão aprovada, sem UTM, tracking ou chaves codificadas. Verifique também se o provedor de envio reescreve links de Auth e configure esses links sem rastreamento de cliques. Não monte manualmente uma URL de verificação nem copie uma de um e-mail real.

5. Atualize e teste primeiro Confirm sign up

No projeto de testes, volte a Authentication > Email Templates > Confirm sign up. Preencha Subject com o assunto de confirmação. Alterne Body para source e cole o HTML completo adaptado; confira preview e use Save changes. A prévia ajuda a revisar o layout, mas não comprova a renderização de uma ação real nem o funcionamento da autenticação.

• Pela aplicação existente, faça um novo cadastro controlado com um endereço elegível. Para uma conta de teste ainda não confirmada, use a função de reenvio da confirmação já implementada na aplicação. Um convite dispara outro tipo de e-mail.
• No e-mail novo, confira texto, assunto, imagens bloqueadas, leitura móvel e o botão nos clientes que seus usuários utilizam.
• Abra a ação e verifique a origem esperada da aplicação e o estado de confirmação da conta.
• Use uma solicitação nova quando precisar testar novamente. Respeite o navegador e o contexto exigidos pelo fluxo existente; não clique repetidamente em um link antigo de uso único.

Esse teste envia um e-mail real. Confira primeiro seu resultado antes de repetir solicitações. Só avance para o outro template depois de validar a confirmação; assim, você consegue identificar qual mudança causou um eventual problema.

6. Atualize Reset password e complete a recuperação

Agora abra Reset password. Use seu próprio backup e confira novamente a expressão da ação. Preencha o Subject de redefinição, cole o HTML da segunda variante e salve com Save changes. Reaproveitar o visual não significa copiar a lógica de callback do cadastro para a recuperação.

• Na aplicação, acione “Esqueci minha senha” para uma conta de teste existente que pertença a você.
• Abra o e-mail recém-recebido e siga o botão até o formulário de nova senha da aplicação.
• Defina a nova senha no aplicativo e confirme que consegue entrar com ela. Apenas abrir o link não conclui a redefinição.
• Confira também assunto, texto, botão, imagens e leitura no celular nessa variante.

Uma resposta de sucesso ao pedir recuperação não comprova envio para um endereço desconhecido. Use a conta existente correta. Não exponha no artigo, nos registros compartilhados ou nas capturas a senha, os códigos ou o link recebido. O resultado final precisa ser o login funcionando após a troca.

Diagnóstico antes de mudar a configuração de produção

Se a mudança impedir uma ação que antes funcionava, restaure o Subject e o Body anteriores apenas do template afetado e teste novamente. Guarde a versão problemática para comparação. Evite alterar vários templates e a configuração de autenticação ao mesmo tempo.

Mantenha design, HTML e template identificados

Salve por tipo de e-mail o projeto Mailvex, o HTML exportado, a versão adaptada e o backup do Supabase. Em toda nova exportação, repita a substituição do marcador e as verificações. O projeto visual não atualiza um template já salvo no Supabase. Preserve as imagens usadas e teste o evento correspondente após mudanças relevantes.

Perguntas frequentes

O Mailvex envia o e-mail ou cria a recuperação de senha?

Não. Ele prepara o design e exporta HTML. Supabase e o envio configurado processam a mensagem; a aplicação precisa ter o fluxo de autenticação e o formulário de nova senha funcionando.

Por que adaptar a expressão depois de exportar?

É um ponto explícito de revisão entre design e autenticação, não uma afirmação de que o editor rejeita a expressão Go. O procedimento permite conferir a ação aprovada e todos os destinos do botão antes de salvar o template.

Isso torna os e-mails da aplicação multilíngues?

Não automaticamente. Traduzir este design ou ler o guia em outro idioma não define como sua aplicação seleciona o idioma de envio. Essa decisão depende da implementação existente e precisa de testes próprios.