Capítulo 12 de 59

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:

  1. 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.
  2. 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

  1. Acesse mailtrap.io e crie ou acerte login na sua conta.
  2. No menu lateral esquerdo, navegue até Email Testing > Inboxes.
  3. Crie uma nova caixa de entrada ou utilize a padrão (ex: Vertis Staging Inbox).
  4. Clique em Show Credentials e selecione a aba SMTP.
  5. Copie os parâmetros exibidos:
    • Host: sandbox.smtp.mailtrap.io
    • Port: 2525 (ou 587)
    • Username: (identificador alfanumérico gerado pelo Mailtrap)
    • Password: (senha alfanumérica gerada pelo Mailtrap)

Passo 2: Configurar o Custom SMTP no Supabase Dashboard

  1. Acesse o painel do seu projeto de Dev ou Staging no Supabase Dashboard.
  2. No menu lateral esquerdo, acesse Authentication > Providers.
  3. Expanda a seção Email.
  4. Role até o final da página e localize o bloco Custom SMTP.
  5. Ative a chave seletora (Enable Custom SMTP: ON).
  6. 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)
  7. 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):

  1. Nenhum e-mail chegará à caixa postal do João, garantindo zero ruído e zero risco de vazamento de dados de homologação.
  2. A mensagem aparecerá em menos de 1 segundo na sua Inbox do Mailtrap.
  3. 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)
Cuidado

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.