Os fluxos de email são uma das partes mais difíceis de testar corretamente numa aplicação web. As confirmações de registo, os resets de palavra-passe, os emails transacionais, as sequências de onboarding — todos requerem uma caixa de entrada funcional para serem verificados.

Usar endereços de email reais para isso é uma má ideia: enche as caixas de entrada, arrisca enviar emails de teste a utilizadores reais e não escala para testes automatizados. Os endereços de email descartáveis e temporários resolvem os três problemas.

Este guia cobre o conjunto completo de ferramentas — desde testes manuais rápidos com uma caixa temporária até à verificação de emails totalmente automatizada em pipelines CI/CD.

O Problema Fundamental com os Testes de Email

Quando constróis um fluxo de email, precisas de verificar:

O email foi realmente enviado
Foi entregue (sem rejeições nem filtros de spam)
O conteúdo está correto (assunto, corpo, links)
Os links no email funcionam corretamente (links de confirmação, tokens de reset de palavra-passe)
O fluxo completa corretamente após o clique no link

Fazer isso com endereços de email reais cria vários problemas:

Poluição das caixas de entrada — As caixas da tua equipa enchem-se com centenas de emails de teste
Envios acidentais a utilizadores reais — Uma variável de ambiente mal configurada e os teus emails de teste vão para utilizadores de produção
Sem acesso programático — Não podes ler uma caixa real a partir de um pipeline CI/CD sem OAuth ou configuração IMAP
Ciclos de feedback lentos — Verificar manualmente uma caixa real para cada execução de teste não escala

Categorias de Ferramentas para Testes de Email

Existem quatro abordagens principais, cada uma adequada a situações diferentes:

1. Caixas de Entrada Descartáveis Públicas (Testes Manuais)

Serviços como InstantTempEmail, Guerrilla Mail ou 10 Minute Mail dão-te uma caixa funcional instantaneamente. Usa-os quando estás a testar manualmente um fluxo e só precisas de receber rapidamente um email de verificação.

Quando usar:

Testes de desenvolvimento local de um novo fluxo de email
Verificações QA pontuais durante o desenvolvimento
Testar como o teu email é renderizado numa caixa real

Quando não usar:

Testes automatizados — não podes ler estas caixas programaticamente num conjunto de testes

2. Interceptores SMTP de Desenvolvimento (Automatizados, Isolados)

Estas ferramentas interceptam todos os emails saídos no teu ambiente de desenvolvimento ou staging — nada é realmente entregue a endereços reais. Inspecionas os emails capturados através de uma interface web ou API.

Mailtrap é o mais utilizado. Configuras a tua aplicação para enviar através do servidor SMTP deles em ambientes não-produção. Todos os emails vão para uma caixa sandbox.

MailHog é uma alternativa auto-alojada — uma aplicação Go leve que executa um servidor SMTP e uma interface web localmente. Zero custo, zero dependência externa.

Mailpit é um substituto mais recente do MailHog com melhor interface e desenvolvimento ativo.

3. Caixas de Entrada API Públicas (Automatizadas, Com Acesso à Caixa)

Serviços como o Mailinator fornecem caixas de entrada acessíveis via API HTTP. Envias email para testuser@mailinator.com a partir da tua aplicação, depois verificas a caixa através da API deles no teu conjunto de testes.

Quando usar:

Testes de ponta a ponta que precisam de verificar o conteúdo do email e clicar em links
Pipelines CI/CD onde precisas de acesso à caixa sem OAuth
Testar fluxos acionados por email (confirmação → redirecionamento → onboarding)

4. Serviços de Teste de Email Transacional

Serviços como o Mailtrap (o produto de teste deles, separado do sandbox), o modo de teste do Postmark ou o modo sandbox do SendGrid testam o pipeline completo de envio de email — chamadas API, renderização, entregabilidade — sem realmente enviar.

Configurar o MailHog para Desenvolvimento Local

O MailHog é a forma mais fácil de configurar testes de email localmente. Executa um servidor SMTP que captura todo o correio saído e exibe-o numa interface web.

Instalação com Docker Compose

Adiciona o MailHog ao teu docker-compose.yml:

services:
  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"   # Porta SMTP
      - "8025:8025"   # Porta interface web
    restart: unless-stopped

Configura a tua aplicação para usar o MailHog

No teu .env para desenvolvimento:

MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=null

Todos os emails que a tua aplicação envia em desenvolvimento vão agora para o MailHog. Acede à caixa em http://localhost:8025.

Por que isto é melhor do que o email real em desenvolvimento

Os emails nunca saem da tua máquina — sem envios acidentais a utilizadores reais
Entrega instantânea — sem esperar pela entrega SMTP real
Conteúdo completo do email visível no browser — cabeçalhos, HTML, partes de texto, anexos
Sem autenticação necessária
Fácil de limpar entre execuções de teste

Testes de Email Automatizados com a API do Mailinator

Para testes de ponta a ponta que precisam de ler emails programaticamente, a API do Mailinator é a opção mais direta.

O nível gratuito tem limites, mas a API paga deles é acessível para a maioria das equipas.

Verificação básica de caixa com fetch

async function getLatestEmail(inboxName) {
  const response = await fetch(
    `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/${inboxName}`,
    {
      headers: {
        Authorization: process.env.MAILINATOR_API_KEY
      }
    }
  )

  const data = await response.json()

  if (!data.msgs || data.msgs.length === 0) {
    throw new Error(`Nenhum email encontrado na caixa: ${inboxName}`)
  }

  return data.msgs[0] // Email mais recente
}

async function getEmailBody(messageId) {
  const response = await fetch(
    `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/test/messages/${messageId}`,
    {
      headers: {
        Authorization: process.env.MAILINATOR_API_KEY
      }
    }
  )

  return response.json()
}

Teste de registo de ponta a ponta completo com Playwright

import { test, expect } from '@playwright/test'

const TEST_EMAIL = `e2e-test-${Date.now()}@mailinator.com`

test('registo de utilizador e confirmação por email', async ({ page }) => {
  // Passo 1: Registar no site
  await page.goto('https://staging.tuaapp.com/register')
  await page.fill('[name="email"]', TEST_EMAIL)
  await page.fill('[name="password"]', 'TestPassword123!')
  await page.click('[type="submit"]')

  // Esperar redirecionamento para a página "verifica o teu email"
  await expect(page).toHaveURL(/check-email/)

  // Passo 2: Aguardar e obter o email de confirmação
  const email = await waitForEmail(TEST_EMAIL.split('@')[0], {
    timeout: 30000,
    subject: 'Confirma o teu email'
  })

  // Passo 3: Extrair o link de confirmação do corpo do email
  const confirmUrl = extractConfirmationLink(email.body)
  expect(confirmUrl).toBeTruthy()

  // Passo 4: Visitar o link de confirmação
  await page.goto(confirmUrl)

  // Passo 5: Verificar confirmação bem-sucedida
  await expect(page).toHaveURL(/dashboard/)
  await expect(page.locator('h1')).toContainText('Bem-vindo')
})

async function waitForEmail(inbox, options = {}) {
  const { timeout = 15000, subject } = options
  const startTime = Date.now()

  while (Date.now() - startTime < timeout) {
    const response = await fetch(
      `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/${inbox}`,
      { headers: { Authorization: process.env.MAILINATOR_API_KEY } }
    )

    const data = await response.json()
    const emails = data.msgs || []

    const match = subject
      ? emails.find(e => e.subject?.includes(subject))
      : emails[0]

    if (match) {
      // Obter o corpo completo do email
      const bodyResponse = await fetch(
        `https://mailinator.com/api/v2/domains/mailinator.com/inboxes/${inbox}/messages/${match.id}`,
        { headers: { Authorization: process.env.MAILINATOR_API_KEY } }
      )
      return bodyResponse.json()
    }

    await new Promise(resolve => setTimeout(resolve, 1000))
  }

  throw new Error(`Email não recebido em ${timeout}ms`)
}

function extractConfirmationLink(emailBody) {
  const htmlContent = emailBody.parts?.[0]?.body || ''
  const urlPattern = /https?:\/\/[^\s"'<>]+confirm[^\s"'<>]*/i
  const match = htmlContent.match(urlPattern)
  return match?.[0] || null
}

Usar Endereços Únicos por Execução de Teste

Um erro comum é reutilizar o mesmo endereço de email de teste entre execuções. Emails antigos poluem a caixa e os testes podem apanhar o email errado.

Padrão: endereços únicos baseados em timestamp

// Gerar uma caixa única por execução de teste
const testRunId = Date.now()
const email = `registration-test-${testRunId}@mailinator.com`

Padrão: baseado em UUID por teste

import { randomUUID } from 'crypto'

function testEmail(prefix = 'test') {
  return `${prefix}-${randomUUID().slice(0, 8)}@mailinator.com`
}

// Utilização
const email = testEmail('registration') // registration-a1b2c3d4@mailinator.com

Isto garante que cada execução de teste tem uma caixa nova sem histórico.

Configurar o Mailpit (Substituto Moderno do MailHog)

O Mailpit tem melhor interface, desenvolvimento ativo e mais funcionalidades do que o MailHog. É a melhor escolha para novas configurações.

# docker-compose.yml
services:
  mailpit:
    image: axllent/mailpit
    ports:
      - "1025:1025"   # SMTP
      - "8025:8025"   # Interface web
    environment:
      MP_MAX_MESSAGES: 500
      MP_DATABASE: /data/mailpit.db
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
    volumes:
      - mailpit_data:/data

volumes:
  mailpit_data:

O Mailpit também tem uma API REST para acesso programático à caixa, tornando-o viável para testes automatizados num ambiente Docker Compose:

// API do Mailpit — para uso em configurações Docker Compose locais/CI
async function getMailpitInbox() {
  const response = await fetch('http://localhost:8025/api/v1/messages')
  return response.json()
}

async function deleteAllMessages() {
  await fetch('http://localhost:8025/api/v1/messages', { method: 'DELETE' })
}

Limpa a caixa no início de cada execução de teste com deleteAllMessages() para garantir um estado limpo.

Prevenir Envios Acidentais para Produção

Isto é crítico. Uma variável de ambiente mal configurada que aponta o staging para as credenciais SMTP de produção irá enviar emails reais a utilizadores reais.

Abordagem 1: Comutação SMTP baseada no ambiente

// email.config.js
const emailConfig = {
  development: {
    host: 'localhost',
    port: 1025,
    secure: false,
    auth: null
  },
  test: {
    host: 'localhost',
    port: 1025,
    secure: false,
    auth: null
  },
  staging: {
    host: process.env.MAILHOG_HOST || 'mailhog',
    port: 1025,
    secure: false
  },
  production: {
    host: process.env.SMTP_HOST,
    port: 587,
    secure: true,
    auth: {
      user: process.env.SMTP_USER,
      pass: process.env.SMTP_PASS
    }
  }
}

export const smtpConfig = emailConfig[process.env.NODE_ENV] || emailConfig.development

Abordagem 2: Lista de permissões de domínios para ambientes não-produção

function shouldSendEmail(toAddress) {
  if (process.env.NODE_ENV === 'production') return true

  const allowedTestDomains = [
    'mailinator.com',
    'guerrillamail.com',
    'instanttempemail.com',
    'tuaempresa.com'  // Endereços de teste internos
  ]

  const domain = toAddress.split('@')[1]
  return allowedTestDomains.includes(domain)
}

Testar a Renderização de Emails em Diferentes Clientes

As ferramentas acima verificam a entrega e o conteúdo dos emails, mas não como o email é renderizado em diferentes clientes. O HTML dos emails comporta-se de forma diferente no Gmail, Outlook, Apple Mail e clientes móveis.

Para testes de renderização, usa Email on Acid ou Litmus — renderizam capturas de ecrã do teu email em mais de 90 clientes. Ambos têm versões de avaliação gratuitas.

Para verificações mais simples, a funcionalidade de pré-visualização de email do Mailtrap renderiza o teu email em contextos de clientes comuns.

Perguntas Frequentes

Posso usar o Gmail ou o Outlook para testes automatizados? Tecnicamente sim, usando OAuth ou acesso IMAP. Na prática, é mais lento, mais complexo de configurar e introduz limites de taxa e gestão de autenticação. As ferramentas dedicadas são sempre mais rápidas e fiáveis.

Qual é a diferença entre o Mailtrap e o MailHog? O Mailtrap é um serviço SaaS alojado — os teus emails são enviados para os servidores deles e visíveis na interface web deles. O MailHog é auto-alojado — corre na tua máquina ou na tua configuração Docker Compose. O MailHog tem zero custo e zero dados saindo do teu ambiente. O Mailtrap é mais fácil de partilhar entre uma equipa.

É seguro usar o Mailinator para dados de teste sensíveis? Não. As caixas do Mailinator são públicas — qualquer pessoa que conheça o nome da caixa pode ler os emails. Usa apenas dados de teste. Nunca uses dados de utilizadores reais nas caixas do Mailinator. Para testes automatizados privados, usa o MailHog ou o Mailpit na tua configuração Docker Compose.

Como testo fluxos de email num pipeline CI do GitHub Actions? Adiciona um serviço MailHog ou Mailpit ao teu workflow do GitHub Actions usando a chave services no YAML do teu workflow. A tua aplicação envia para localhost:1025, e os teus testes leem através da API local.

jobs:
  test:
    services:
      mailpit:
        image: axllent/mailpit
        ports:
          - 1025:1025
          - 8025:8025

Devo testar com fornecedores de email reais em staging? Apenas se precisares especificamente de testar a entregabilidade (pontuação de spam, DKIM/DMARC, colocação na caixa de entrada). Para testes funcionais de fluxos de email, um interceptor local como o MailHog é mais rápido e seguro. Realiza verificações de entregabilidade reais separadamente, com menos frequência, usando contas de teste nos principais fornecedores.

Como os desenvolvedores usam emails descartáveis para testes (com exemplos reais)