Mailtrap no Supabase: Interceptando E-mails em Dev e Staging
Interceptação Segura de E-mails no Supabase Cloud: Como Configurar Mailtrap em Dev e Staging
Durante o ciclo de desenvolvimento local com o Supabase CLI rodando via Docker, a captura de e-mails transacionais é transparente: o Mailpit embutido roda silenciosamente na porta 54324 e intercepta qualquer confirmação de cadastro, recuperação de senha ou convite enviado pelo sistema.
No entanto, quando o projeto avança na esteira de CI/CD para a nuvem — criando instâncias de Desenvolvimento (Dev), Homologação (Staging) ou ambientes efêmeros de Database Branching no Supabase Cloud —, o Mailpit local deixa de existir.
Nesse momento, surge um dilema crítico de engenharia:
- O Risco de Vazamento (Email Leak): Se o ambiente de testes utilizar um provedor de envio real (como Resend ou Amazon SES), e-mails de homologação contendo links quebrados, dados de teste ou convites disparados para endereços fictícios/reais serão efetivamente entregues nas caixas postais de pessoas reais.
- O Bloqueio de Testes: Se o ambiente de Staging não tiver um provedor SMTP configurado, o Supabase Cloud aplicará o rate limit restrito do serviço padrão (apenas 3 e-mails por hora) e os desenvolvedores/QA não conseguirão abrir e clicar nos Magic Links de autenticação.
A solução padrão ouro que eu adoto é conectar o Mailtrap Email Testing como servidor Custom SMTP dedicado para todos os projetos de não-produção no Supabase Cloud.
⚠️ A Cláusula Financeira do Mailtrap
Em conformidade com as minhas diretrizes arquiteturais:
- Plano Gratuito (Email Testing Free): O Mailtrap oferece uma conta gratuita com 1 Inbox e capacidade para capturar até 100 e-mails de teste por mês, com retenção de mensagens por 3 dias. É 100% suficiente para desenvolvimento individual e provas de conceito (PoC).
- Planos Pagos (Individual / Team): Para times de engenharia com esteiras ativas de CI/CD, testes end-to-end automatizados (Playwright) ou múltiplos projetos (Dev, Staging e QA), os planos iniciam em aproximadamente $14,99/mês, liberando múltiplas inboxes isoladas, capacidade de 5.000+ e-mails de teste e retenção estendida.
1. O Funcionamento da Caixa de Interceptação (Sandbox SMTP)
O Mailtrap funciona como um servidor SMTP com "buraco negro seguro". Ele aceita as conexões do Supabase Auth, recebe a mensagem, renderiza o HTML e cabeçalhos em um painel web protegido por senha e descarta o envio para a internet pública:
┌─────────────────────────────────────────────────────────────┐
│ NEXT.JS APP (DEV / STAGING) │
│ Dispara convite de usuário: inviteUserByEmail() │
└──────────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ SUPABASE AUTH (DEV CLOUD) │
│ Processa o evento de autenticação no banco │
│ Dispara o envio via Custom SMTP configurado │
└──────────────────────────────┬──────────────────────────────┘
│
(Conexão SMTP TLS / Porta 2525)
▼
┌─────────────────────────────────────────────────────────────┐
│ MAILTRAP (SANDBOX DE TESTES) │
│ - Captura 100% dos e-mails na nuvem │
│ - Bloqueia entrega para caixas postais reais │
│ - Exibe Magic Links, HTML e Headers para o time de QA │
└─────────────────────────────────────────────────────────────┘
2. Passo a Passo: Configuração do Mailtrap no Supabase Cloud
Passo 1: Criar a Inbox de Testes no Mailtrap
- Acesse mailtrap.io e crie ou acerte login na sua conta.
- No menu lateral esquerdo, navegue até Email Testing > Inboxes.
- Crie uma nova caixa de entrada ou utilize a padrão (ex:
Vertis Staging Inbox). - Clique em Show Credentials e selecione a aba SMTP.
- Copie os parâmetros exibidos:
- Host:
sandbox.smtp.mailtrap.io - Port:
2525(ou587) - Username:
(identificador alfanumérico gerado pelo Mailtrap) - Password:
(senha alfanumérica gerada pelo Mailtrap)
- Host:
Passo 2: Configurar o Custom SMTP no Supabase Dashboard
- Acesse o painel do seu projeto de Dev ou Staging no Supabase Dashboard.
- No menu lateral esquerdo, acesse Authentication > Providers.
- Expanda a seção Email.
- Role até o final da página e localize o bloco Custom SMTP.
- Ative a chave seletora (Enable Custom SMTP: ON).
- Preencha os campos com as credenciais obtidas no Mailtrap:
- Sender Email:
nao-responda@dev.vertis.com.br(qualquer e-mail fictício com o domínio do projeto) - Sender Name:
Vertis Dev(ou o nome do seu projeto em Staging) - Host:
sandbox.smtp.mailtrap.io - Port Number:
2525 - Username:
(seu username do Mailtrap) - Password:
(sua senha do Mailtrap)
- Sender Email:
- Clique no botão Save para persistir as alterações.
3. Disparando e Validando Convites de Usuários
Com a integração ativa, qualquer ação que dispare e-mails transacionais no Supabase será capturada instantaneamente pelo Mailtrap.
Exemplo em Server Action do Next.js:
// app/actions/invite-team-member.ts
"use server";
import { createServerClient } from "@/lib/supabase/server";
import { createClient } from "@supabase/supabase-js";
export async function inviteTeamMemberAction(email: string) {
// 1. Valida permissao do usuario logado (Admin)
const supabase = await createServerClient();
const { data: { user } } = await supabase.auth.getUser();
if (!user) {
throw new Error("Sessao invalida.");
}
// 2. Instancia o client com Service Role para executar o convite
const supabaseAdmin = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.SUPABASE_SERVICE_ROLE_KEY!
);
// 3. Dispara o convite institucional
const { data, error } = await supabaseAdmin.auth.admin.inviteUserByEmail(
email,
{
redirectTo: "https://staging.vertis.com.br/auth/callback",
data: {
invited_by: user.id,
role: "operator",
},
}
);
if (error) {
throw new Error(`Erro ao enviar convite: ${error.message}`);
}
return { success: true, user: data.user };
}
O Resultado no Painel do Mailtrap:
Assim que a Server Action for invocada (mesmo disparada para um e-mail corporativo como joao@empresa.com.br):
- Nenhum e-mail chegará à caixa postal do João, garantindo zero ruído e zero risco de vazamento de dados de homologação.
- A mensagem aparecerá em menos de 1 segundo na sua Inbox do Mailtrap.
- O desenvolvedor ou analista de QA pode abrir a mensagem, inspecionar a formatação HTML, verificar a pontuação de spam e clicar diretamente no botão / link mágico de confirmação para completar o teste de onboarding.
4. A Regra de Ouro da Segregação de Ambientes
Para manter uma esteira de software corporativa 100% blindada contra incidentes, adote a seguinte matriz estrita de provedores SMTP:
| Ambiente | Provedor SMTP Configurado | Objetivo Primário | Risco de Entrega Real |
|---|---|---|---|
| Local (Docker) | Mailpit (Porta 54324) | Desenvolvimento offline na máquina do engenheiro | Zero (Localhost) |
| Dev / Staging (Cloud) | Mailtrap (Sandbox SMTP) | Homologação na nuvem, testes manuais e E2E | Zero (Interceptação Cloud) |
| Produção (Prod) | Resend / Amazon SES | Entrega oficial e com reputação SPF/DKIM | 100% Real (Clientes finais) |
Aviso Crítico de Segurança: Jamais utilize as credenciais de SMTP de Produção (como chaves de API do Resend, SendGrid ou Amazon SES) em projetos do Supabase configurados como Development ou Staging. O erro humano ao testar disparos em massa em bases de teste pode queimar a reputação do seu domínio corporativo e enviar links de homologação confidenciais para clientes reais.
Conclusão: Engenharia de Testes de Nível Corporativo
A configuração do Mailtrap como Custom SMTP no Supabase Cloud fecha a lacuna entre o desenvolvimento local e os ambientes de nuvem.
Com essa arquitetura simples e robusta, sua equipe de desenvolvimento ganha total autonomia para testar fluxos complexos de onboarding, convites corporativos e recuperações de credenciais com velocidade, enquanto a governança de dados da empresa permanece 100% protegida contra vazamentos acidentais de e-mail.
Se a sua empresa busca estruturar esteiras de CI/CD contínuas, ambientes seguros de homologação ou sistemas corporativos escaláveis com Next.js e Supabase, conheça meus serviços de desenvolvimento sob medida ou solicite um diagnóstico de arquitetura comigo.