Introdução

A funcionalidade de email é um pilar das aplicações web modernas. Seja para criar um formulário de contato, um sistema de autenticação de usuários ou um serviço de notificações, entender como lidar com email no lado do servidor é essencial. Este guia apresenta a implementação de funcionalidade de email no SvelteKit usando Nodemailer, com foco nos padrões modernos do Svelte 5 e nas boas práticas.

O que é o Nodemailer?

Nodemailer é um módulo Node.js que simplifica o envio de emails. Ele suporta vários métodos de transporte (SMTP, Gmail, SendGrid, etc.) e lida com a complexidade dos protocolos de email por você. No contexto do SvelteKit, o Nodemailer é executado exclusivamente no servidor, mantendo as credenciais sensíveis seguras.

O que Você vai Aprender

Ao final deste guia, você entenderá:

Como configurar o Nodemailer com variáveis de ambiente
Como criar handlers de email no lado do servidor
Como construir formulários com aprimoramento progressivo no Svelte 5
Como implementar validação de formulários com Valibot
Como lidar com múltiplos destinos de email com actions nomeadas
Como gerenciar o estado do formulário e o tratamento de erros
Implementações com segurança de tipos usando TypeScript

Pré-requisitos

Entendimento básico de roteamento e form actions no SvelteKit
Node.js instalado (v18 ou posterior recomendado)
Uma conta Gmail ou serviço SMTP para testes

Configuração do Projeto

Primeiro, instale as dependências necessárias:

npm install nodemailer
npm install -D @types/nodemailer  # TypeScript types
npm install valibot  # For validation

Configuração de Ambiente

Credenciais de email nunca devem ser codificadas diretamente no código. O SvelteKit fornece módulos de variáveis de ambiente exclusivos para segredos do servidor que nunca são expostos ao cliente.

Entendendo as Variáveis de Ambiente do SvelteKit:

O SvelteKit oferece dois tipos de variáveis de ambiente privadas:

$env/dynamic/private - Lidas em tempo de execução a partir de arquivos .env. Ideal para desenvolvimento local e quando variáveis de ambiente são injetadas na inicialização do container/servidor. Os valores podem mudar sem necessidade de rebuild.
$env/static/private - Substituídas em tempo de build como literais de string. Ideal para implantações serverless (Vercel, Netlify) onde as variáveis de ambiente são conhecidas durante o build. Habilita tree-shaking e melhor desempenho.

Usamos $env/dynamic/private pois o foco está no desenvolvimento local, onde você deseja que as alterações no .env entrem em vigor ao reiniciar o servidor de desenvolvimento sem precisar fazer rebuild. Ao implantar em produção, considere $env/static/private se sua plataforma suportar variáveis de ambiente em tempo de build para melhor desempenho.

1. Criar as Variáveis de Ambiente

Crie um arquivo .env na raiz do seu projeto:

# .env
GOOGLE_EMAIL="your-email@gmail.com"
GOOGLE_EMAIL_PASSWORD="your-app-specific-password"

Importante: Para o Gmail, você precisa de uma Senha de App, não da sua senha comum. Ative a verificação em duas etapas na sua conta Google e, em seguida, gere uma senha específica para o aplicativo.

2. Atualizar o .gitignore

Garanta que seu arquivo .env nunca seja commitado:

# .gitignore
.env
.env.*
!.env.example

3. Criar o .env.example

Forneça um template para outros desenvolvedores:

# .env.example
GOOGLE_EMAIL=""
GOOGLE_EMAIL_PASSWORD=""

Configurando o Transporter de Email

O transporter é sua conexão com o serviço de email. Vamos criar um módulo reutilizável exclusivo para o servidor.

Entendendo a Convenção .server.js

Arquivos terminados em .server.js são a forma do SvelteKit de declarar módulos exclusivos do servidor. Eles nunca podem ser importados em código do lado do cliente, fornecendo uma camada extra de segurança para operações sensíveis.

Criar a Configuração de Email

// src/lib/mailer/emailSetup.server.ts

import nodemailer from 'nodemailer'
import type { Transporter } from 'nodemailer'
import { env } from '$env/dynamic/private'

/**
 * Creates and verifies email transporter
 */
function createTransporter(): Transporter {
	const transporter = nodemailer.createTransport({
		host: 'smtp.gmail.com',
		port: 465, // SSL port
		secure: true, // Use SSL
		auth: {
			user: env.GOOGLE_EMAIL,
			pass: env.GOOGLE_EMAIL_PASSWORD
		}
	})

	// Verify connection on startup
	transporter.verify((error, success) => {
		if (error) {
			console.error('Email transporter error:', error)
		} else {
			console.log('✓ Email server ready to send messages')
		}
	})

	return transporter
}

// Create singleton instance
export const transporter = createTransporter()

Alternativa: Usando Outros Serviços de Email

O Nodemailer suporta vários serviços. Aqui estão alternativas comuns:

SendGrid

SendGrid é um popular serviço de entrega de email baseado em nuvem:

// src/lib/mailer/emailSetup.server.ts
import type { Transporter } from 'nodemailer'

const transporter: Transporter = nodemailer.createTransport({
	host: 'smtp.sendgrid.net',
	port: 587,
	auth: {
		user: 'apikey',
		pass: SENDGRID_API_KEY
	}
})

Mailgun

Mailgun oferece APIs de email poderosas e serviços SMTP:

// src/lib/mailer/emailSetup.server.ts
import type { Transporter } from 'nodemailer'

const transporter: Transporter = nodemailer.createTransport({
	host: 'smtp.mailgun.org',
	port: 587,
	auth: {
		user: MAILGUN_SMTP_LOGIN,
		pass: MAILGUN_SMTP_PASSWORD
	}
})

AWS SES

Amazon SES fornece infraestrutura de email escalável e econômica:

// src/lib/mailer/emailSetup.server.ts
import { SES } from '@aws-sdk/client-ses'
import type { Transporter } from 'nodemailer'

const ses = new SES({
	apiVersion: '2010-12-01',
	region: 'us-east-1'
})

const transporter: Transporter = nodemailer.createTransport({
	SES: { ses, aws }
})

SendPigeon

SendPigeon (GitHub) é um serviço moderno de email transacional projetado para desenvolvedores:

// src/lib/mailer/emailSetup.server.ts
// Using SendPigeon SDK (recommended)
import { SendPigeon } from 'sendpigeon'
import { SENDPIGEON_API_KEY } from '$env/dynamic/private'

const client = new SendPigeon(SENDPIGEON_API_KEY)

// Send email
await client.emails.send({
	from: 'hello@yourdomain.com',
	to: recipientEmail,
	subject: 'Your subject',
	html: '<h1>Your HTML content</h1>'
})

Recursos:

Excelente integração com SvelteKit
Suporte a TypeScript
99,9% de entregabilidade
Servidor de email local gratuito para testes
Construtor de email drag-and-drop gratuito

Opinião: Por que Começar com Nodemailer no Svelte 5

Embora serviços baseados em API como SendGrid, Mailgun e SendPigeon ofereçam praticidade e sofisticação, o Nodemailer continua sendo a melhor base para aprender sobre email em projetos SvelteKit.

Por que Começar com Nodemailer:

Compreensão antes da Abstração: O Nodemailer obriga você a entender como o email realmente funciona — conexões SMTP, estrutura de mensagens, cabeçalhos, autenticação. Serviços baseados em API abstraem tudo isso, o que é conveniente, mas deixa lacunas no seu modelo mental quando algo dá errado.
Integração com Testes Locais: O Nodemailer integra-se perfeitamente com servidores SMTP locais (Mailpit, MailCrab, smtp4dev) e o Ethereal Email. Você pode testar fluxos completos de email offline, sem chaves de API, limites de taxa ou dependências externas. Isso torna o desenvolvimento mais rápido e confiável.
Consistência de Arquitetura: Com o Nodemailer, sua arquitetura de email não muda entre desenvolvimento e produção — você simplesmente troca as credenciais SMTP. Serviços baseados em API frequentemente exigem padrões de código diferentes para testes versus produção, adicionando complexidade.
Zero Lock-In: O Nodemailer funciona com qualquer provedor SMTP. Uma vez que você o entende, alternar entre Gmail, SendGrid, AWS SES ou um servidor de email personalizado é apenas uma questão de configuração. Soluções baseadas em API prendem você ao ecossistema delas.
Escalabilidade em Produção: O Nodemailer escala de formulários de contato simples a email transacional em nível empresarial sem mudanças arquiteturais. Sistemas de filas (BullMQ) e pooling de conexões funcionam da mesma forma, independentemente de você enviar 10 ou 10.000 emails por dia.

Quando Considerar Alternativas Baseadas em API:

Após dominar o básico: Uma vez que você entende SMTP, estrutura de mensagens e entregabilidade, serviços baseados em API se tornam ferramentas valiosas de produtividade, e não caixas-pretas.
Para recursos específicos: Análises de email, testes A/B, sistemas avançados de templates e otimização dedicada de entregabilidade justificam as trocas do lock-in de fornecedor.
Em escala significativa: Quando você está enviando milhões de emails por mês, serviços gerenciados oferecem infraestrutura que você não quer ter que manter sozinho.

O Caminho de Aprendizado:

Comece aqui: Domine o Nodemailer + ferramentas de teste locais
Adicione preocupações de produção: Sistemas de filas, monitoramento, limitação de taxa
Então otimize: Considere serviços baseados em API quando a conveniência superar o custo da abstração

Alternativas baseadas em API são excelentes — mas são trade-offs intencionais, não substituições. Aprenda os fundamentos com o Nodemailer primeiro, depois escolha a ferramenta certa para suas necessidades específicas.

Construindo o Componente de Formulário de Contato

Vamos criar um formulário de contato com aprimoramento progressivo usando os padrões modernos do Svelte 5.

Vamos usar a action enhance do $app/forms para lidar com envios de formulário sem JavaScript, enquanto ainda fornece uma experiência fluida quando o JavaScript está disponível.

Criar o Componente de Formulário

<!-- src/routes/contact/+page.svelte -->
<script lang="ts">
	import { enhance } from '$app/forms'

	/**
	 * @type {import('./$types').PageProps}
	 * PageProps includes both data (from load) and form (from actions)
	 */
	let { data, form } = $props()

	// Track form submission state
	let isSubmitting = $state(false)

	// Type-safe helper for field errors
	const fieldErrors = (
		errors: Record<string, string[]> | { _form: string[] } | undefined,
		field: string
	) => (errors && field in errors ? (errors as Record<string, string[]>)[field] : undefined)
</script>

<div class="container">
	<h1>Contact Us</h1>

	{#if form?.success}
		<div class="success-message" role="alert">
			<p>✓ Thank you! Your message has been sent successfully.</p>
		</div>
	{/if}

	<form
		method="POST"
		use:enhance={() => {
			// Before submission
			isSubmitting = true

			return async ({ result, update }) => {
				// After submission
				isSubmitting = false

				// Apply default behavior (updates form prop, resets on success)
				await update()
			}
		}}
	>
		<div class="form-field">
			<label for="name">
				Name
				{#if fieldErrors(form?.errors, 'name')}
					<span class="error">{fieldErrors(form?.errors, 'name')?.[0]}</span>
				{/if}
			</label>
			<input
				id="name"
				name="name"
				type="text"
				value={form?.data?.name ?? ''}
				aria-invalid={fieldErrors(form?.errors, 'name') ? 'true' : undefined}
				required
			/>
		</div>

		<div class="form-field">
			<label for="email">
				Email
				{#if fieldErrors(form?.errors, 'email')}
					<span class="error">{fieldErrors(form?.errors, 'email')?.[0]}</span>
				{/if}
			</label>
			<input
				id="email"
				name="email"
				type="email"
				value={form?.data?.email ?? ''}
				aria-invalid={fieldErrors(form?.errors, 'email') ? 'true' : undefined}
				required
			/>
		</div>

		<div class="form-field">
			<fieldset class="checkbox-fieldset">
				<legend>
					Services Interested In
					{#if fieldErrors(form?.errors, 'service')}
						<span class="error">{fieldErrors(form?.errors, 'service')?.[0]}</span>
					{/if}
				</legend>
				<div class="checkbox-group">
					{#each ['Web Development', 'Mobile Apps', 'Consulting', 'Design'] as service}
						<label class="checkbox-label">
							<input
								type="checkbox"
								name="service"
								value={service}
								checked={form?.data?.service?.includes(service) ?? false}
							/>
							{service}
						</label>
					{/each}
				</div>
			</fieldset>
		</div>

		<div class="form-field">
			<label for="budget">
				Budget Range
				{#if fieldErrors(form?.errors, 'budget')}
					<span class="error">{fieldErrors(form?.errors, 'budget')?.[0]}</span>
				{/if}
			</label>
			<select id="budget" name="budget" value={form?.data?.budget ?? ''} required>
				<option value="">Select a range</option>
				<option value="< $5,000">Less than $5,000</option>
				<option value="$5,000 - $10,000">$5,000 - $10,000</option>
				<option value="$10,000 - $25,000">$10,000 - $25,000</option>
				<option value="$25,000+">$25,000+</option>
			</select>
		</div>

		<div class="form-field">
			<label for="message">
				Message
				{#if fieldErrors(form?.errors, 'message')}
					<span class="error">{fieldErrors(form?.errors, 'message')?.[0]}</span>
				{/if}
			</label>
			<textarea
				id="message"
				name="message"
				rows="5"
				value={form?.data?.message ?? ''}
				aria-invalid={fieldErrors(form?.errors, 'message') ? 'true' : undefined}
				required
			></textarea>
		</div>

		<button type="submit" disabled={isSubmitting}>
			{isSubmitting ? 'Sending...' : 'Send Message'}
		</button>
	</form>
</div>

<style>
	.container {
		max-width: 600px;
		margin: 2rem auto;
		padding: 0 1rem;
	}

	.success-message {
		background: #d4edda;
		border: 1px solid #c3e6cb;
		color: #155724;
		padding: 1rem;
		border-radius: 0.25rem;
		margin-bottom: 1.5rem;
	}

	.form-field {
		margin-bottom: 1.5rem;
	}

	.checkbox-fieldset {
		border: none;
		padding: 0;
		margin: 0;
	}

	.checkbox-fieldset legend {
		font-weight: 600;
		margin-bottom: 0.5rem;
		padding: 0;
	}

	label {
		display: block;
		font-weight: 600;
		margin-bottom: 0.5rem;
	}

	.error {
		color: #dc3545;
		font-size: 0.875rem;
		font-weight: normal;
		margin-left: 0.5rem;
	}

	input[type='text'],
	input[type='email'],
	select,
	textarea {
		width: 100%;
		padding: 0.5rem;
		border: 1px solid #ced4da;
		border-radius: 0.25rem;
		font-size: 1rem;
	}

	input[aria-invalid='true'],
	textarea[aria-invalid='true'] {
		border-color: #dc3545;
	}

	.checkbox-group {
		display: flex;
		flex-direction: column;
		gap: 0.5rem;
	}

	.checkbox-label {
		display: flex;
		align-items: center;
		gap: 0.5rem;
		font-weight: normal;
	}

	button {
		background: #007bff;
		color: white;
		padding: 0.75rem 1.5rem;
		border: none;
		border-radius: 0.25rem;
		font-size: 1rem;
		cursor: pointer;
		transition: background 0.2s;
	}

	button:hover:not(:disabled) {
		background: #0056b3;
	}

	button:disabled {
		opacity: 0.6;
		cursor: not-allowed;
	}
</style>

O formulário agora está totalmente funcional com aprimoramento progressivo. Ele funcionará sem JavaScript, pois o formulário ainda opera por meio do envio nativo de formulários HTML, mas com JavaScript você obtém:

Sem recarregamento completo da página
Estados de carregamento
Atualizações otimistas de UI
Tratamento de erros

Validação

Antes de enviar emails, devemos validar a entrada do usuário. Embora existam outras bibliotecas de validação como o Zod, utilizamos o Valibot, que oferece segurança de tipos em tempo de execução com excelente tree-shaking e é oficialmente suportado pelo Svelte.

Por que Valibot?

Leve: ~1-2KB minificado (Zod tem ~14KB)
Tree-Shakeable: Empacota apenas o que você usa
Type Safety: Integração completa com TypeScript
Composável: Encadeie múltiplas validações
Suporte Oficial: Recomendado pela equipe do Svelte
API Moderna: Abordagem limpa e funcional

Criar Schema de Validação

Vamos criar um schema de validação para os dados do nosso formulário de contato. Isso garantirá que apenas dados válidos sejam processados e que mensagens de erro significativas sejam fornecidas aos usuários.

// src/lib/types.ts

import * as v from 'valibot'

/**
 * Contact form validation schema
 * Provides both type safety and runtime validation
 */
export const contactEmailSchema = v.object({
	name: v.pipe(
		v.string('Name is required'),
		v.nonEmpty('Name is required'),
		v.minLength(2, 'Name must be at least 2 characters'),
		v.maxLength(100, 'Name must be less than 100 characters'),
		v.trim()
	),

	email: v.pipe(
		v.string('Email is required'),
		v.nonEmpty('Email is required'),
		v.email('Please enter a valid email address'),
		v.maxLength(254, 'Email is too long'), // RFC 5321
		v.toLowerCase(),
		v.trim()
	),

	service: v.pipe(
		v.array(v.string()),
		v.minLength(1, 'Please select at least one service'),
		v.maxLength(4, 'Please select no more than 4 services')
	),

	budget: v.pipe(
		v.string('Please select a budget range'),
		v.nonEmpty('Please select a budget range')
	),

	message: v.pipe(
		v.string('Message is required'),
		v.nonEmpty('Message is required'),
		v.minLength(10, 'Message must be at least 10 characters'),
		v.maxLength(1000, 'Message must be less than 1000 characters'),
		v.trim()
	)
})

// Type inference for use in TypeScript files
export type ContactEmailData = v.InferOutput<typeof contactEmailSchema>

Actions no Servidor

As actions de formulário são a forma preferida do SvelteKit para lidar com envios de formulários. Elas são executadas no servidor, mantendo operações sensíveis seguras.

Entendendo as Actions de Formulário

As actions de formulário são funções executadas no servidor que:

Recebem requisições POST de formulários
Processam FormData
Podem validar, transformar e armazenar dados
Retornam dados de volta ao cliente
Funcionam sem JavaScript (progressive enhancement)

Criar a Action Padrão

O SvelteKit permite que você defina uma action default que é executada quando um formulário é enviado sem um parâmetro action explícito. Isso é ideal para o nosso formulário de contato.

// src/routes/contact/+page.server.ts

import { env } from '$env/dynamic/private'
import { transporter } from '$lib/mailer/emailSetup.server'
import { contactEmailSchema, type ContactEmailData } from '$lib/types'
import { fail, type Actions, type RequestEvent } from '@sveltejs/kit'
import * as v from 'valibot'

export const actions: Actions = {
	/**
	 * Default action - handles form submission
	 * Runs when form is submitted without an explicit action parameter
	 */
	default: async ({ request }: RequestEvent) => {
		// Extract form data
		const formData = await request.formData()

		const contactEmailData = {
			name: formData.get('name') as string,
			email: formData.get('email') as string,
			service: formData.getAll('service') as string[],
			budget: formData.get('budget') as string,
			message: formData.get('message') as string
		}

		try {
			// Validate data with Valibot
			const validatedData = v.parse(contactEmailSchema, contactEmailData)

			// Send email
			await sendContactEmail(validatedData)

			// Return success response
			return {
				success: true
			}
		} catch (err) {
			// Handle validation errors
			if (v.isValiError(err)) {
				const fieldErrors: Record<string, string[]> = {}

				// Convert Valibot issues to field-specific errors
				for (const issue of err.issues) {
					const path = issue.path?.[0]?.key as string
					if (path) {
						if (!fieldErrors[path]) {
							fieldErrors[path] = []
						}
						fieldErrors[path].push(issue.message)
					}
				}

				// Return errors and form data for repopulation
				return fail(400, {
					errors: fieldErrors,
					data: contactEmailData
				})
			}

			// Handle email sending errors
			console.error('Email error:', err)
			return fail(500, {
				errors: {
					_form: ['Failed to send message. Please try again later.']
				},
				data: contactEmailData
			})
		}
	}
}

/**
 * Sends contact form email
 */
async function sendContactEmail(data: ContactEmailData): Promise<void> {
	// Build HTML email template
	const html = `
		<!DOCTYPE html>
		<html>
		<head>
			<style>
				body {
					font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
					line-height: 1.6;
					color: #333;
				}
				.email-container {
					max-width: 600px;
					margin: 0 auto;
					padding: 20px;
				}
				.email-header {
					background: #f8f9fa;
					padding: 20px;
					border-radius: 8px 8px 0 0;
					border-bottom: 3px solid #007bff;
				}
				.email-body {
					background: white;
					padding: 20px;
					border: 1px solid #e9ecef;
					border-top: none;
				}
				.info-table {
					width: 100%;
					border-collapse: collapse;
					margin: 20px 0;
				}
				.info-table th {
					background: #f8f9fa;
					padding: 12px;
					text-align: left;
					font-weight: 600;
					border: 1px solid #dee2e6;
				}
				.info-table td {
					padding: 12px;
					border: 1px solid #dee2e6;
				}
				.message-section {
					margin-top: 20px;
					padding: 15px;
					background: #f8f9fa;
					border-left: 4px solid #007bff;
				}
				.services-list {
					list-style: none;
					padding: 0;
				}
				.services-list li:before {
					content: "✓ ";
					color: #28a745;
					font-weight: bold;
					margin-right: 8px;
				}
			</style>
		</head>
		<body>
			<div class="email-container">
				<div class="email-header">
					<h2 style="margin: 0; color: #007bff;">New Contact Form Submission</h2>
				</div>
				<div class="email-body">
					<table class="info-table">
						<tr>
							<th>Name</th>
							<td>${escapeHtml(data.name)}</td>
						</tr>
						<tr>
							<th>Email</th>
							<td><a href="mailto:${data.email}">${escapeHtml(data.email)}</a></td>
						</tr>
						<tr>
							<th>Budget Range</th>
							<td>${escapeHtml(data.budget)}</td>
						</tr>
						<tr>
							<th>Services</th>
							<td>
								<ul class="services-list">
									${data.service.map((s) => `<li>${escapeHtml(s)}</li>`).join('')}
								</ul>
							</td>
						</tr>
					</table>
					
					<div class="message-section">
						<h3 style="margin-top: 0;">Message</h3>
						<p style="white-space: pre-wrap;">${escapeHtml(data.message)}</p>
					</div>
				</div>
			</div>
		</body>
		</html>
	`

	// Configure email message
	const message = {
		from: `"${data.name}" <${data.email}>`,
		replyTo: data.email, // Allows direct reply to sender
		to: env.GOOGLE_EMAIL,
		subject: `New Contact Form: ${data.name} - ${data.service[0]}`,
		html,
		// Plain text fallback
		text: `
			Name: ${data.name}
			Email: ${data.email}
			Budget: ${data.budget}
			Services: ${data.service.join(', ')}
			
			Message:
			${data.message}
		`
	}

	// Send email (Promise-based, works for dev + prod)
	const info = await transporter.sendMail(message)

	if (!info.messageId) {
		console.error('Failed to send email:', info)
	} else {
		console.log('✓ Email sent:', info.messageId)
	}
}

/**
 * Escapes HTML to prevent XSS attacks
 * Essential when including user input in HTML emails
 */
function escapeHtml(unsafe: string): string {
	return unsafe
		.replace(/&/g, '&amp;')
		.replace(/</g, '&lt;')
		.replace(/>/g, '&gt;')
		.replace(/"/g, '"')
		.replace(/'/g, '&#039;')
}

Conceitos-Chave Explicados

1. A Função `fail`

A função fail do SvelteKit retorna erros sem acionar os error boundaries:

import { fail } from '@sveltejs/kit'

// Returns 400 status with error data
return fail(400, {
	errors: { email: ['Invalid email'] },
	data: { name: 'John' }
})

Sem fail, retornar erros acionaria a página de erro.

2. Métodos do FormData

formData.get('name') as string // Single value
formData.getAll('service') as string[] // Multiple values (checkboxes)

3. Tratamento de Erros do Valibot

catch (err) {
	if (v.isValiError(err)) {
		// Validation errors - convert to field errors
		const fieldErrors: Record<string, string[]> = {};
		for (const issue of err.issues) {
			const path = issue.path?.[0]?.key as string;
			if (path) {
				fieldErrors[path] = fieldErrors[path] || [];
				fieldErrors[path].push(issue.message);
			}
		}
		return fail(400, { errors: fieldErrors });
	}

	// Other errors (network, email service, etc.)
	return fail(500, { errors: { _form: ['General error'] } });
}

4. Segurança em E-mails HTML

Sempre escape a entrada do usuário em e-mails HTML para evitar ataques XSS:

${escapeHtml(data.message)}  // Safe
${data.message}              // Dangerous!

É tudo que você precisa... mais ou menos

Se sua página contém um único formulário e você concluiu todos os passos necessários — incluindo a configuração correta de uma Senha de App do Google — esta configuração é tudo que você precisa. Os envios de formulário devem enviar e-mails com sucesso para o endereço designado.

Neste ponto, você terminou. A sério. Se esse é o seu caso de uso, pode parar aqui e colocar no ar.

Dito isso, projetos reais raramente permanecem simples para sempre. Se você precisar lidar com cenários mais avançados — múltiplos formulários, diferentes destinos de e-mail ou fluxos de trabalho mais estruturados — continue lendo.

Antes de mergulharmos nos padrões avançados, certifique-se de que os fundamentos estão sólidos. Teste seu formulário usando um dos provedores de teste de e-mail recomendados, verifique se os e-mails estão sendo enviados de fato e confirme que a validação se comporta exatamente como esperado. Depurar lógica "avançada" em cima de uma base quebrada é perda de tempo.

Quando o básico estiver consolidado e você estiver confiante de que tudo funciona de ponta a ponta, você está pronto para ir mais fundo.

Vamos além.

Entendendo as Actions de Formulário: Do Simples ao Avançado

Quando você está aprendendo sobre funcionalidade de e-mail com Nodemailer, uma pergunta surge com frequência: "Meu formulário deve ter um botão de envio ou múltiplos?"

A resposta depende de quem está tomando a decisão e que decisão está sendo tomada. Vamos construir seu entendimento passo a passo.

Comece Aqui: O Padrão de Action Única

A maioria das aplicações — incluindo a sua — deve começar com o padrão mais simples: um formulário, uma action, um botão.

Veja como é um formulário de contato pronto para produção:

<!-- src/routes/contact/+page.svelte -->
<script lang="ts">
	import { enhance } from '$app/forms'

	let { form } = $props()
	let isSubmitting = $state(false)
</script>

<form
	method="POST"
	use:enhance={() => {
		isSubmitting = true
		return async ({ update }) => {
			isSubmitting = false
			await update()
		}
	}}
>
	<label>
		Name
		<input name="name" required />
	</label>

	<label>
		Email
		<input name="email" type="email" required />
	</label>

	<label>
		Message
		<textarea name="message" required></textarea>
	</label>

	<button type="submit" disabled={isSubmitting}>
		{isSubmitting ? 'Sending...' : 'Send Message'}
	</button>
</form>

A action no servidor lida com toda a lógica de e-mail em um único lugar:

// src/routes/contact/+page.server.ts
import { fail } from '@sveltejs/kit'
import type { Actions } from './$types'
import { transporter } from '$lib/mailer/emailSetup.server'
import { env } from '$env/dynamic/private'

export const actions: Actions = {
	default: async ({ request }) => {
		const formData = await request.formData()

		const data = {
			name: formData.get('name') as string,
			email: formData.get('email') as string,
			message: formData.get('message') as string
		}

		try {
			// Email 1: Notify admin about new message
			await transporter.sendMail({
				to: env.ADMIN_EMAIL,
				from: env.COMPANY_EMAIL,
				replyTo: data.email,
				subject: `Contact Form: ${data.name}`,
				text: `From: ${data.name} (${data.email})\n\n${data.message}`
			})

			// Email 2: Send confirmation to user
			await transporter.sendMail({
				to: data.email,
				from: env.COMPANY_EMAIL,
				subject: 'We received your message',
				text: `Hi ${data.name},\n\nThanks for contacting us. We've received your message and will respond within 24 hours.\n\nBest regards,\nThe Team`
			})

			return { success: true }
		} catch (error) {
			console.error('Email error:', error)
			return fail(500, { error: 'Failed to send message' })
		}
	}
}

Observe o que está acontecendo aqui:

O usuário vê um botão → O servidor envia dois e-mails → Ambos têm sucesso ou ambos falham juntos.

Este é o padrão correto para 95% das aplicações.

Por que Isso Funciona

Pense no modelo mental do usuário. Quando alguém preenche um formulário de contato, ele está pensando:

"Quero enviar uma mensagem"

Ele não está pensando:

"Devo notificar o admin ou a equipe de vendas?"
"Quero um e-mail de confirmação?"
"Isso deve ir para a fila prioritária?"

Essas são suas preocupações como desenvolvedor, não as preocupações do usuário. Lide com elas no servidor, onde elas pertencem.

Benefícios de formulários com action única:

✅ Usuários não podem cometer erros (sem botão errado para clicar)
✅ Você controla o fluxo de e-mail de forma centralizada
✅ Fácil de adicionar rate limiting, validação e logging
✅ Simples de testar e manter
✅ Funciona sem JavaScript (progressive enhancement)

Se este padrão resolve o seu problema, você terminou. Coloque no ar. Os padrões abaixo são para cenários mais avançados.

Quando Você Precisa de Múltiplas Actions

Às vezes os usuários genuinamente precisam escolher o que acontece com seus dados. É aqui que as named actions se tornam úteis.

Reconhecendo o Padrão

Pergunte a si mesmo: "O usuário está fazendo uma escolha consciente sobre o resultado?"

Exemplos onde os usuários fazem escolhas:

Cenário	Decisão do Usuário	Resultado de E-mail
Enviar recibo	"Apenas enviar ao cliente" vs "Enviar + guardar uma cópia"	Comportamento de BCC diferente
Formulário de contato	"Enviar agora" vs "Salvar rascunho"	E-mail vs sem e-mail
Fluxo de aprovação	"Aprovar" vs "Solicitar alterações"	Templates de e-mail diferentes

Exemplos onde os usuários NÃO fazem escolhas:

Cenário	O que Realmente Acontece	Padrão Correto
Formulário de contato	Sempre notifica o admin + confirma ao usuário	Action única, múltiplos e-mails
Inscrição em newsletter	Sempre confirma + notifica a equipe	Action única, múltiplos e-mails
Recibo de pedido	Sempre envia e-mail ao cliente + contabilidade	Action única, múltiplos e-mails

A distinção-chave: O usuário está decidindo o resultado, ou o sistema está seguindo regras?

Construindo o Entendimento: O Exemplo do Recibo

Vamos explorar um cenário real onde múltiplas actions fazem sentido.

A situação: Você gerencia uma loja de e-commerce. Após um pedido, você precisa enviar o recibo por e-mail ao cliente. Às vezes você quer uma cópia para seus registros, às vezes não.

A abordagem errada:

<!-- ❌ Don't do this -->
<form method="POST">
	<label>
		<input type="checkbox" name="sendCopy" />
		Send me a copy
	</label>
	<button type="submit">Send Receipt</button>
</form>

Por que isso está errado? Você está usando uma action mas tentando lidar com dois comportamentos diferentes. O servidor precisa verificar if (sendCopy) { ... }, o que cria lógica de ramificação.

A abordagem correta com named actions:

<!-- ✅ Clear user intent -->
<script lang="ts">
	import { enhance } from '$app/forms'

	let { form } = $props()
	let isSubmitting = $state(false)
	let wantsCopy = $state(false)
</script>

<form
	method="POST"
	use:enhance={() => {
		isSubmitting = true
		return async ({ update }) => {
			isSubmitting = false
			await update()
		}
	}}
>
	<input name="orderNumber" type="text" placeholder="Order #" required />
	<input name="customerEmail" type="email" placeholder="Customer email" required />

	<label>
		<input type="checkbox" bind:checked={wantsCopy} />
		Send me a copy
	</label>

	{#if wantsCopy}
		<input name="yourEmail" type="email" placeholder="Your email" required />
	{/if}

	{#if wantsCopy}
		<button type="submit" formaction="?/sendWithCopy" disabled={isSubmitting}>
			Send Receipt + Copy
		</button>
	{:else}
		<button type="submit" formaction="?/sendReceipt" disabled={isSubmitting}> Send Receipt </button>
	{/if}
</form>

Percebeu o atributo formaction? Ele informa ao navegador qual action do servidor deve ser chamada. Sem necessidade de roteamento JavaScript.

O Lado do Servidor

Cada action é focada e explícita:

// src/routes/orders/receipt/+page.server.ts
import { fail } from '@sveltejs/kit'
import type { Actions } from './$types'
import { transporter } from '$lib/mailer/emailSetup.server'
import { env } from '$env/dynamic/private'

export const actions: Actions = {
	/**
	 * Send receipt to customer only
	 */
	sendReceipt: async ({ request }) => {
		const data = await request.formData()

		await transporter.sendMail({
			to: data.get('customerEmail'),
			from: env.COMPANY_EMAIL,
			subject: `Receipt for Order #${data.get('orderNumber')}`,
			html: createReceiptHTML(data)
		})

		return { success: true }
	},

	/**
	 * Send receipt to customer + BCC yourself
	 */
	sendWithCopy: async ({ request }) => {
		const data = await request.formData()

		await transporter.sendMail({
			to: data.get('customerEmail'),
			from: env.COMPANY_EMAIL,
			bcc: data.get('yourEmail'), // Hidden copy
			subject: `Receipt for Order #${data.get('orderNumber')}`,
			html: createReceiptHTML(data)
		})

		return { success: true }
	}
}

function createReceiptHTML(data: FormData): string {
	return `
		<h1>Order Receipt</h1>
		<p>Order Number: ${data.get('orderNumber')}</p>
		<p>Thank you for your purchase!</p>
	`
}

O que torna isso bom?

Separação clara: Cada action faz uma coisa
Sem condicionais: Sem lógica if (wantsCopy) no servidor
Intenção explícita: O nome da action documenta o que acontece
Fácil de testar: Teste cada action independentemente

Entendendo formaction

O atributo formaction é nativo do HTML. Ele substitui o atributo action padrão do formulário para aquele botão específico.

<form method="POST" action="/default">
	<button type="submit">Uses /default</button>
	<button type="submit" formaction="/other">Uses /other instead</button>
</form>

No SvelteKit, você usa a sintaxe ?/actionName:

<form method="POST">
	<button type="submit" formaction="?/sendReceipt">Send Receipt</button>
	<button type="submit" formaction="?/sendWithCopy">Send + Copy</button>
</form>

Isso mapeia para suas server actions:

export const actions = {
	sendReceipt: async () => {
		/* ... */
	},
	sendWithCopy: async () => {
		/* ... */
	}
}

Por que usar formaction em vez de JavaScript?

Aprimoramento progressivo. O formulário funciona mesmo se o JavaScript falhar ao carregar. O navegador lida nativamente com o roteamento para diferentes endpoints.

Equívocos Comuns

Vamos abordar alguns mal-entendidos sobre quando usar múltiplas actions:

1: Múltiplos departamentos precisam de múltiplas actions

Exemplo do que NÃO fazer:

<!-- ❌ Bad: User shouldn't know your org chart -->
<form method="POST">
	<label>
		<input type="radio" name="dept" value="sales" />
		Contact Sales
	</label>
	<label>
		<input type="radio" name="dept" value="support" />
		Contact Support
	</label>
	<button type="submit">Send</button>
</form>

Por que isso é ruim:

Usuários esquecem de selecionar um departamento
Usuários escolhem o departamento errado
Sua estrutura organizacional não é problema do usuário

Melhor abordagem: Uma action, roteamento inteligente:

export const actions: Actions = {
	default: async ({ request }) => {
		const data = await request.formData()
		const message = data.get('message') as string

		// Smart routing based on message content
		const recipient = message.toLowerCase().includes('billing')
			? env.BILLING_EMAIL
			: env.SUPPORT_EMAIL

		await transporter.sendMail({
			to: recipient,
			subject: 'Contact Form Submission',
			text: message
		})
	}
}

2: Teste vs Produção = Múltiplas actions

Exemplo do que NÃO fazer:

<!-- ❌ Bad: Don't expose test mode to production users -->
<form method="POST">
	<button type="submit" formaction="?/sendTest">Test Mode</button>
	<button type="submit" formaction="?/sendReal">Send Real</button>
</form>

Melhor abordagem: Use detecção de ambiente:

import { dev } from '$app/environment'

export const actions: Actions = {
	default: async ({ request }) => {
		const recipient = dev
			? 'test@ethereal.email' // Dev environment
			: env.CUSTOMER_EMAIL // Production

		await transporter.sendMail({
			to: recipient
			// ...
		})
	}
}

Framework de Decisão

Use este fluxograma para decidir qual padrão utilizar:

Does the user need to consciously choose what happens?
│
├─ NO → Use single action (default pattern)
│        Example: Contact form, Newsletter signup
│
└─ YES → Does the choice change the email behavior?
          │
          ├─ YES → Use named actions + formaction
          │        Example: Send receipt vs Send receipt + copy
          │
          └─ NO → Use single action with parameters
                   Example: Priority level (handle server-side)

Perguntas para se fazer:

"Se eu removesse essa escolha, os usuários ficariam confusos?"
- Se NÃO → Action única
- Se SIM → Múltiplas actions
"Essa escolha é sobre entrega de e-mail ou lógica de aplicação?"
- Entrega de e-mail → Named actions
- Lógica de aplicação → Tratar no servidor
"Um usuário poderia acidentalmente escolher a opção errada?"
- Se SIM → Abstração errada, simplifique

Testando Seu Entendimento

Antes de prosseguir, tente responder estas perguntas:

Cenário 1: Você tem um formulário "Reportar Bug". Os usuários devem escolher entre "Alta Prioridade" e "Baixa Prioridade" usando dois botões de envio?

Clique para revelar a resposta

Não. Isso é avaliação de severidade, não roteamento de e-mail. Use um único botão de envio e deixe o servidor (ou administrador) determinar a prioridade com base na descrição do bug. Se for necessário capturar a prioridade, use um dropdown no formulário, não múltiplas actions.

export const actions: Actions = {
	default: async ({ request }) => {
		const priority = formData.get('priority'); // from dropdown
		const recipient = priority === 'high'
			? env.URGENT_EMAIL
			: env.BUGS_EMAIL;

		await sendEmail({ to: recipient, ... });
	}
};

Cenário 2: Você tem um formulário "Enviar Fatura". Você deve ter botões separados para "Enviar por E-mail ao Cliente" e "Enviar por E-mail ao Cliente + Contabilidade"?

Clique para revelar a resposta

Talvez. Isso depende do seu processo de negócio:

Se a contabilidade SEMPRE precisa de uma cópia → Action única, sempre envie para ambos
Se a contabilidade precisa APENAS às vezes → Named actions faz sentido
Se você não tem certeza → Comece com action única (sempre envie para ambos), pode refatorar depois

A questão-chave: "O contador precisa de TODAS as faturas, ou apenas algumas?"

Cenário 3: Seu formulário de assinatura envia confirmação ao usuário e notificação para sua equipe de marketing. Quantas actions?

Clique para revelar a resposta

Uma action. O usuário não está escolhendo entre resultados - ele está apenas se inscrevendo. O fato de sua equipe ser notificada é um detalhe de implementação interno, não uma escolha do usuário.

export const actions: Actions = {
	default: async ({ request }) => {
		// Email 1: To subscriber
		await sendConfirmation(email)

		// Email 2: To team (user doesn't choose this)
		await notifyTeam(email)
	}
}

Resumo: O Padrão Certo para Sua Situação

Use Action Única (Padrão) Quando:

✅ O usuário quer "enviar" ou "submeter" algo
✅ Múltiplos e-mails são SUA lógica de negócio, não escolha do usuário
✅ Você não tem certeza de qual padrão usar (comece simples!)

Exemplo: Formulários de contato, inscrições em newsletter, confirmações de pedido

Use Named Actions Quando:

✅ O usuário escolhe conscientemente entre diferentes resultados
✅ A escolha altera o comportamento do e-mail (destinatários, timing, conteúdo)
✅ Cada action tem um propósito claro e distinto

Exemplo: "Enviar recibo" vs "Enviar recibo + cópia para mim"

Evite Múltiplas Actions Quando:

❌ O usuário está escolhendo entre SEUS departamentos
❌ Você está expondo modos de teste/debug
❌ A "escolha" é realmente apenas um parâmetro

Solução: Trate o roteamento no servidor com lógica inteligente

Se você tiver interesse em aprender mais sobre padrões e técnicas avançadas, pode ler o artigo Advanced Email Templates, onde exploramos como criar um sistema profissional de templates de e-mail.

Testando a Funcionalidade de E-mail

Ao desenvolver funcionalidades de e-mail, evite usar endereços de e-mail reais em ambientes de desenvolvimento. Em vez disso, utilize soluções modernas de teste de e-mail projetadas para fluxos de trabalho seguros e eficazes. Nesta seção, exploraremos as ferramentas mais confiáveis para testar o Nodemailer dentro de uma aplicação SvelteKit.

1. Ethereal Email (Recomendado para Testes Rápidos)

Ethereal Email é um serviço SMTP mock gratuito criado para testar o Nodemailer. Os e-mails são interceptados e visualizáveis em uma caixa de entrada web, nunca entregues de fato:

// src/lib/mailer/emailSetup.server.ts

import nodemailer from 'nodemailer'
import type { Transporter } from 'nodemailer'
import { dev } from '$app/environment'

async function createTransporter(): Promise<Transporter> {
	// Use Ethereal in development
	if (dev) {
		const testAccount = await nodemailer.createTestAccount()

		const transporter = nodemailer.createTransport({
			host: 'smtp.ethereal.email',
			port: 587,
			secure: false,
			auth: {
				user: testAccount.user,
				pass: testAccount.pass
			}
		})

		// Log preview URL for each email
		const originalSendMail = transporter.sendMail.bind(transporter)
		transporter.sendMail = async (mailOptions) => {
			const info = await originalSendMail(mailOptions)
			console.log('Preview URL:', nodemailer.getTestMessageUrl(info))
			return info
		}

		return transporter
	}

	// Use real SMTP in production
	return nodemailer.createTransport({
		host: 'smtp.gmail.com',
		port: 465,
		secure: true,
		auth: {
			user: process.env.GOOGLE_EMAIL,
			pass: process.env.GOOGLE_EMAIL_PASSWORD
		}
	})
}

export const transporter = await createTransporter()

Como funciona

A vantagem do Ethereal é que você não precisa se cadastrar nem configurar nada. O Ethereal gera automaticamente uma conta temporária para você cada vez que você executa seu aplicativo em modo de desenvolvimento. Quando você envia um e-mail, o Ethereal registra uma URL de prévia no console. Clique na URL para visualizar o e-mail na interface web do Ethereal.

Execute seu aplicativo SvelteKit em modo de desenvolvimento
Preencha o formulário de contato e envie
Verifique o terminal por um log como: Preview URL: https://ethereal.email/message/...
Clique na URL para visualizar o e-mail na interface web do Ethereal

Cada vez que você envia um e-mail, uma nova URL de prévia é registrada, permitindo que você visualize cada e-mail separadamente. As contas expiram após 24 horas, garantindo um ambiente de teste limpo e sem desordem.

Fluxo de trabalho de teste:

npm run dev  # Start your app
# Fill out the contact form and submit
# Check terminal for: "Preview URL: https://ethereal.email/message/..."
# Click the URL to view the email in new browser tab

Este fluxo de trabalho é ideal para testes rápidos e desenvolvimento sem o risco de enviar e-mails reais. Para cenários de teste mais avançados, você pode explorar outras ferramentas como Mailpit ou MailCrab, que oferecem recursos adicionais como armazenamento de mensagens, pesquisa e acesso via API.

Isso corresponde à sua experiência usando o Ethereal? Ou você acha que os leitores precisam de mais/menos detalhes aqui?

Também noto que as outras ferramentas de teste (Mailpit, MailCrab, etc.) têm o mesmo problema - elas mostram a instalação, mas não as etapas do "e agora?". Devemos adicionar explicações de fluxo de trabalho semelhantes para essas também?

2. Mailpit (Servidor SMTP Local Moderno)

Mailpit (GitHub) é um servidor SMTP local moderno, ativamente mantido, com uma bela interface web:

# Install via Homebrew (macOS)
brew install mailpit

# Or download binary from GitHub
# https://github.com/axllent/mailpit/releases

# Run Mailpit
mailpit

Configure transporter:

// src/lib/mailer/emailSetup.server.ts
import type { Transporter } from 'nodemailer'

const transporter: Transporter = nodemailer.createTransport({
	host: 'localhost',
	port: 1025,
	secure: false
})

Veja os e-mails em http://localhost:8025

Recursos:

UI moderna e responsiva
Pesquisa e filtragem
Visualização HTML/Texto
Visualização de anexos
Marcação de mensagens
API para automação
Multiplataforma (Windows, macOS, Linux)
Desenvolvimento ativo (ao contrário do Mailhog)

3. MailCrab (Alternativa Leve em Rust)

MailCrab (GitHub) é uma ferramenta de teste de e-mail super leve escrita em Rust:

# Install via Cargo
cargo install mailcrab

# Or download binary from GitHub
# https://github.com/tweedegolf/mailcrab/releases

# Run MailCrab
mailcrab

Configure transporter:

// src/lib/mailer/emailSetup.server.ts
import type { Transporter } from 'nodemailer'

const transporter: Transporter = nodemailer.createTransport({
	host: 'localhost',
	port: 1025,
	secure: false
})

Veja os e-mails em http://localhost:1080

Recursos:

Muito rápido e leve (~5MB de binário)
UI limpa e simples
Atualizações em tempo real via WebSockets
Amigável para dispositivos móveis
Sem dependências

4. smtp4dev (Multiplataforma com Docker)

smtp4dev é um servidor de teste de e-mail moderno e ativamente mantido, com excelente suporte a Docker. Ele é executado como uma aplicação .NET com uma UI web e é particularmente popular entre desenvolvedores .NET, embora funcione muito bem para qualquer projeto Node.js.

# Run with Docker
docker run -p 3000:80 -p 2525:25 rnwood/smtp4dev

# Or install globally via .NET
dotnet tool install -g Rnwood.Smtp4dev
smtp4dev

Configure transporter:

// src/lib/mailer/emailSetup.server.js
const transporter = nodemailer.createTransport({
	host: 'localhost',
	port: 2525,
	secure: false
})

Veja os e-mails em http://localhost:3000

Recursos:

UI moderna e sofisticada
Editar e reenviar e-mails
Suporte a relay SMTP
Suporte a Docker
Multiplataforma (.NET)
Acesso à API

5. SendPigeon Local Dev Server

SendPigeon fornece um servidor local de teste de e-mail gratuito, desenvolvido especificamente para aplicações SvelteKit:

# Install SendPigeon CLI
npm install -g sendpigeon

# Start local dev server
sendpigeon dev

Configure for testing:

// src/lib/mailer/emailSetup.server.ts
import { SendPigeon } from 'sendpigeon'
import { dev } from '$app/environment'
import { SENDPIGEON_API_KEY } from '$env/dynamic/private'

const client = new SendPigeon(dev ? 'test_key' : SENDPIGEON_API_KEY, {
	baseUrl: dev ? 'http://localhost:3005' : undefined
})

interface SendEmailOptions {
	to: string
	from: string
	subject: string
	html: string
}

export async function sendEmail({ to, from, subject, html }: SendEmailOptions) {
	return await client.emails.send({
		from,
		to,
		subject,
		html
	})
}

Veja os e-mails em http://localhost:3005

Recursos:

Desenvolvido especificamente para SvelteKit
Captura automática de e-mails
Visualização visual de e-mails
Sem necessidade de configuração SMTP
Suporte a TypeScript
Teste de webhooks
Gratuito e de código aberto

Tabela Comparativa

Ferramenta	Porta SMTP	Porta Web	Instalação	Melhor Para	Links
Ethereal	N/A	N/A	Automática	CI/CD, testes rápidos	Website
Mailpit	1025	8025	Brew/Binário	Desenvolvimento diário	Website \| GitHub
MailCrab	1025	1080	Cargo/Binário	Configuração leve	GitHub
smtp4dev	2525	3000	Docker/.NET	Fluxos com Docker	GitHub
SendPigeon	N/A	3005	npm global	Projetos SvelteKit	Website

Recomendações

Projetos SvelteKit: Use o SendPigeon Local Dev Server para integração perfeita
Desenvolvimento: Use o Mailpit para testes locais ricos em recursos
CI/CD: Use o Ethereal para testes automatizados
Configuração Mínima: Use o MailCrab se quiser algo leve
Projetos com Docker: Use o smtp4dev para fluxos conteinerizados

Para concluir, todas essas ferramentas resolvem o mesmo problema central — testes seguros de e-mail — mas se destacam em cenários diferentes, e essa distinção é importante ao trabalhar com Nodemailer no Svelte 5.

Use Mailpit, MailCrab ou smtp4dev quando quiser um ambiente de desenvolvimento local e determinístico. Essas ferramentas se comportam como servidores SMTP reais, oferecem visibilidade completa sobre cabeçalhos, corpos e anexos, e se integram perfeitamente ao Nodemailer simplesmente alterando o host e a porta. São ideais para o desenvolvimento diário, depuração de templates e validação de casos extremos sem dependências externas. Entre elas, o Mailpit se destaca como a opção mais moderna e performática atualmente.

Escolha o Ethereal quando quiser uma solução baseada em nuvem sem configuração para experimentos rápidos, demonstrações ou exemplos de documentação. É excelente para aprendizado e prototipagem, mas menos adequado para desenvolvimento local de longa duração ou pipelines de CI devido à sua natureza efêmera.

Opte pelo SendPigeon se valorizar um fluxo de trabalho unificado do desenvolvimento à produção. Ele reduz a troca de configurações ao permitir que a mesma configuração do cliente funcione localmente e em ambientes reais, o que pode simplificar projetos em que a entrega de e-mails está intimamente ligada à lógica de negócios.

A principal conclusão:

- Coletores SMTP locais são melhores para controle, realismo e repetibilidade.
- O Ethereal é melhor para testes rápidos e descartáveis.
- O SendPigeon é melhor quando minimizar a divergência entre ambientes é uma prioridade.

Em uma configuração Svelte 5 + Nodemailer, escolha a ferramenta que corresponde à sua filosofia de desenvolvimento — não apenas o que envia e-mails, mas o que mantém seu ciclo de feedback rápido, seguro e previsível.

6. Estratégia Abrangente de Testes

Uma estratégia de testes robusta garante que a funcionalidade de e-mail funcione corretamente em diferentes cenários e ambientes. Esta seção aborda testes unitários, testes de integração, estratégias de mocking e considerações sobre CI/CD.

6.1 Testes Unitários de Form Actions

Comece testando suas form actions de forma isolada. Concentre-se em validação, tratamento de erros e transformação de dados:

// src/routes/contact/contact.test.js

import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { actions } from './+page.server.js'
import * as v from 'valibot'

describe('Contact form action', () => {
	let sendEmailMock

	beforeEach(() => {
		// Mock the email sending function
		sendEmailMock = vi.fn().mockResolvedValue({ messageId: 'test-123' })
	})

	afterEach(() => {
		vi.clearAllMocks()
	})

	describe('Validation', () => {
		it('rejects empty form submission', async () => {
			const request = new Request('http://localhost', {
				method: 'POST',
				body: new FormData()
			})

			const result = await actions.default({ request })

			expect(result.status).toBe(400)
			expect(result.data.errors).toBeDefined()
			expect(result.data.errors.name).toBeDefined()
			expect(result.data.errors.email).toBeDefined()
		})

		it('rejects invalid email format', async () => {
			const formData = new FormData()
			formData.append('name', 'John Doe')
			formData.append('email', 'invalid-email')
			formData.append('service', 'Web Development')
			formData.append('budget', '$5,000 - $10,000')
			formData.append('message', 'Test message')

			const request = new Request('http://localhost', {
				method: 'POST',
				body: formData
			})

			const result = await actions.default({ request })

			expect(result.status).toBe(400)
			expect(result.data.errors.email).toContain('Please enter a valid email address')
		})

		it('rejects message that is too short', async () => {
			const formData = new FormData()
			formData.append('name', 'John Doe')
			formData.append('email', 'john@example.com')
			formData.append('service', 'Web Development')
			formData.append('budget', '$5,000 - $10,000')
			formData.append('message', 'Short') // Less than 10 characters

			const request = new Request('http://localhost', {
				method: 'POST',
				body: formData
			})

			const result = await actions.default({ request })

			expect(result.status).toBe(400)
			expect(result.data.errors.message).toBeDefined()
		})
	})

	describe('Success cases', () => {
		it('accepts valid data', async () => {
			const formData = new FormData()
			formData.append('name', 'John Doe')
			formData.append('email', 'john@example.com')
			formData.append('service', 'Web Development')
			formData.append('budget', '$5,000 - $10,000')
			formData.append('message', 'Test message that is long enough')

			const request = new Request('http://localhost', {
				method: 'POST',
				body: formData
			})

			const result = await actions.default({ request })

			expect(result.success).toBe(true)
		})

		it('handles multiple service selections', async () => {
			const formData = new FormData()
			formData.append('name', 'John Doe')
			formData.append('email', 'john@example.com')
			formData.append('service', 'Web Development')
			formData.append('service', 'Mobile Apps')
			formData.append('budget', '$10,000 - $25,000')
			formData.append('message', 'Need both web and mobile development')

			const request = new Request('http://localhost', {
				method: 'POST',
				body: formData
			})

			const result = await actions.default({ request })

			expect(result.success).toBe(true)
		})
	})

	describe('Data transformation', () => {
		it('trims whitespace from inputs', async () => {
			const formData = new FormData()
			formData.append('name', '  John Doe  ')
			formData.append('email', '  john@example.com  ')
			formData.append('service', 'Web Development')
			formData.append('budget', '$5,000 - $10,000')
			formData.append('message', '  Test message with spaces  ')

			const request = new Request('http://localhost', {
				method: 'POST',
				body: formData
			})

			const result = await actions.default({ request })

			expect(result.success).toBe(true)
			// Verify trimming happened in validation
		})

		it('converts email to lowercase', async () => {
			const formData = new FormData()
			formData.append('name', 'John Doe')
			formData.append('email', 'JOHN@EXAMPLE.COM')
			formData.append('service', 'Web Development')
			formData.append('budget', '$5,000 - $10,000')
			formData.append('message', 'Test message')

			const request = new Request('http://localhost', {
				method: 'POST',
				body: formData
			})

			const result = await actions.default({ request })

			expect(result.success).toBe(true)
		})
	})
})

6.2 Testes de Integração com Serviços de E-mail

Teste a funcionalidade real de envio de e-mails usando seu servidor SMTP de teste:

// tests/integration/email.test.js

import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import nodemailer from 'nodemailer'
import { sendEmail } from '$lib/mailer/sendEmail.server.js'

let testAccount
let transporter

beforeAll(async () => {
	// Create test account for Ethereal Email
	testAccount = await nodemailer.createTestAccount()

	transporter = nodemailer.createTransport({
		host: 'smtp.ethereal.email',
		port: 587,
		secure: false,
		auth: {
			user: testAccount.user,
			pass: testAccount.pass
		}
	})
})

describe('Email integration tests', () => {
	it('sends email successfully', async () => {
		const emailData = {
			to: 'test@example.com',
			from: 'noreply@yourapp.com',
			subject: 'Test Email',
			html: '<h1>Test</h1><p>This is a test email</p>'
		}

		const info = await transporter.sendMail(emailData)

		expect(info.messageId).toBeDefined()
		expect(info.accepted).toContain('test@example.com')

		// Get preview URL
		const previewUrl = nodemailer.getTestMessageUrl(info)
		console.log('Preview URL:', previewUrl)
	})

	it('handles email sending errors gracefully', async () => {
		const invalidTransporter = nodemailer.createTransport({
			host: 'invalid-host.example.com',
			port: 587,
			secure: false
		})

		const emailData = {
			to: 'test@example.com',
			from: 'noreply@yourapp.com',
			subject: 'Test Email',
			html: '<p>Test</p>'
		}

		await expect(invalidTransporter.sendMail(emailData)).rejects.toThrow()
	})
})

6.3 Testando Templates de E-mail

Garanta que seus templates de e-mail sejam renderizados corretamente e tratem casos extremos:

// tests/unit/emailTemplates.test.js

import { describe, it, expect } from 'vitest';
import { contactTemplate } from '$lib/mailer/templates/contact.js';

describe('Email templates', () => {
	describe('contactTemplate', () => {
		it('renders with all required fields', () => {
			const data: ContactEmailData = {
				name: 'John Doe',
				email: 'john@example.com',
				budget: '$5,000 - $10,000',
				service: ['Web Development', 'Mobile Apps'],
				message: 'Test message'
			};

			const html = contactTemplate(data);

			expect(html).toContain('John Doe');
			expect(html).toContain('john@example.com');
			expect(html).toContain('$5,000 - $10,000');
			expect(html).toContain('Web Development');
			expect(html).toContain('Mobile Apps');
			expect(html).toContain('Test message');
		});

		it('escapes HTML in user input', () => {
			const data: ContactEmailData = {
				name: '<script>alert("xss")</script>',
				email: 'test@example.com',
				budget: '$5,000',
				service: ['Web Development'],
				message: '<img src=x onerror=alert(1)>'
			};

			const html = contactTemplate(data);

			// Verify dangerous HTML is escaped
			expect(html).not.toContain('<script>');
			expect(html).toContain('&lt;script&gt;');
			expect(html).not.toContain('<img src=x');
		});

		it('handles special characters correctly', () => {
			const data: ContactEmailData = {
				name: 'José García',
				email: 'jose@example.com',
				budget: '$5,000 - $10,000',
				service: ['Design & Development'],
				message: 'Need help with R&D'
			};

			const html = contactTemplate(data);

			expect(html).toContain('José García');
			expect(html).toContain('&amp;');
		});
	});
});

6.4 Fazendo Mock de Serviços de E-mail

Use mocks para evitar o envio real de e-mails durante os testes:

// tests/mocks/emailMock.js

import { vi } from 'vitest'

export const createMockTransporter = () => ({
	sendMail: vi.fn().mockImplementation((mailOptions, callback) => {
		const info = {
			messageId: 'mock-message-id',
			accepted: [mailOptions.to],
			rejected: [],
			response: '250 Message accepted'
		}

		if (callback) {
			callback(null, info)
		} else {
			return Promise.resolve(info)
		}
	}),
	verify: vi.fn().mockResolvedValue(true)
})

Use the mock in your tests:

// tests/unit/contactAction.test.js

import { describe, it, expect, vi, beforeEach } from 'vitest'
import { createMockTransporter } from '../mocks/emailMock.js'

vi.mock('$lib/mailer/emailSetup.server.js', () => ({
	transporter: createMockTransporter()
}))

describe('Contact action with mocked email', () => {
	it('calls sendMail with correct parameters', async () => {
		// Test implementation
	})
})

6.5 Testes End-to-End com Playwright

Teste o fluxo completo do usuário, incluindo o envio de formulários:

// tests/e2e/contact.spec.js

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

test.describe('Contact form', () => {
	test('submits successfully with valid data', async ({ page }) => {
		await page.goto('/contact')

		// Fill form
		await page.fill('[name="name"]', 'John Doe')
		await page.fill('[name="email"]', 'john@example.com')
		await page.check('[name="service"][value="Web Development"]')
		await page.selectOption('[name="budget"]', '$5,000 - $10,000')
		await page.fill('[name="message"]', 'This is a test message for e2e testing')

		// Submit
		await page.click('button[type="submit"]')

		// Verify success message
		await expect(page.locator('.success-message')).toBeVisible()
		await expect(page.locator('.success-message')).toContainText('Thank you')
	})

	test('shows validation errors for invalid data', async ({ page }) => {
		await page.goto('/contact')

		// Submit empty form
		await page.click('button[type="submit"]')

		// Verify error messages
		await expect(page.locator('.error')).toHaveCount(5) // All fields required
	})

	test('shows loading state during submission', async ({ page }) => {
		await page.goto('/contact')

		// Fill valid data
		await page.fill('[name="name"]', 'John Doe')
		await page.fill('[name="email"]', 'john@example.com')
		await page.check('[name="service"][value="Web Development"]')
		await page.selectOption('[name="budget"]', '$5,000 - $10,000')
		await page.fill('[name="message"]', 'Test message')

		const submitButton = page.locator('button[type="submit"]')

		// Start submission
		await submitButton.click()

		// Verify loading state (button disabled and text changed)
		await expect(submitButton).toBeDisabled()
		await expect(submitButton).toContainText('Sending...')
	})
})

6.6 Integração com CI/CD

Configure os testes em seu pipeline de CI/CD:

# .github/workflows/test.yml

name: Test Email Functionality

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run unit tests
        run: npm run test:unit

      - name: Run integration tests
        run: npm run test:integration
        env:
          # Use Ethereal for CI testing
          NODE_ENV: test

      - name: Install Playwright
        run: npx playwright install --with-deps

      - name: Run E2E tests
        run: npm run test:e2e

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-results
          path: test-results/

6.7 Boas Práticas de Testes

O que fazer:

✅ Testar a lógica de validação minuciosamente
✅ Fazer mock de serviços de e-mail externos em testes unitários
✅ Usar servidores SMTP reais (Ethereal, Mailpit) para testes de integração
✅ Testar o escape de HTML para prevenir XSS
✅ Verificar se os templates de e-mail são renderizados corretamente
✅ Testar o tratamento de erros e a lógica de retry
✅ Incluir testes E2E para fluxos críticos do usuário

O que não fazer:

❌ Enviar e-mails reais em testes automatizados
❌ Codificar credenciais de teste diretamente no código
❌ Pular testes de casos extremos em templates de e-mail
❌ Esquecer de testar o rate limiting
❌ Ignorar cenários de erro

Metas de Cobertura de Testes:

Validação de formulários: 100%
Lógica de envio de e-mails: 90%+
Renderização de templates: 90%+
Caminhos críticos E2E: 100%

Tratamento de Erros e Logging

Ao enviar e-mails, um tratamento de erros robusto é essencial para garantir que os problemas sejam detectados e resolvidos prontamente. Esta seção aborda boas práticas para tratamento de erros, logging e implementação de lógica de retry para melhorar a confiabilidade.

Crie uma função sendEmail abrangente com tratamento de erros aprimorado:

// src/lib/mailer/sendEmail.server.ts

import { transporter } from './emailSetup.server'
import { dev } from '$app/environment'
import type { SentMessageInfo } from 'nodemailer'

interface EmailOptions {
	to: string
	from: string
	replyTo?: string
	subject: string
	html: string
	text?: string
}

/**
 * Error types for better handling
 */
class EmailError extends Error {
	originalError?: Error

	constructor(message: string, originalError?: Error) {
		super(message)
		this.name = 'EmailError'
		this.originalError = originalError
	}
}

/**
 * Sends email with comprehensive error handling
 */
export async function sendEmail({
	to,
	from,
	replyTo,
	subject,
	html,
	text
}: EmailOptions): Promise<SentMessageInfo> {
	// Validate inputs
	if (!to || !from || !subject || !html) {
		throw new EmailError('Missing required email fields')
	}

	try {
		const info = await new Promise<SentMessageInfo>((resolve, reject) => {
			const message = {
				from,
				to,
				replyTo,
				subject,
				html,
				text: text || stripHtml(html)
			}

			transporter.sendMail(message, (err, info) => {
				if (err) {
					reject(err)
				} else {
					resolve(info)
				}
			})
		})

		// Log success
		if (dev) {
			console.log('✓ Email sent:', {
				messageId: info.messageId,
				to,
				subject
			})
		}

		return info
	} catch (err) {
		// Enhanced error logging
		console.error('Email send failed:', {
			to,
			subject,
			error: err.message,
			code: err.code,
			command: err.command
		})

		// Wrap error with context
		throw new EmailError(`Failed to send email to ${to}: ${err.message}`, err)
	}
}

/**
 * Strips HTML tags for plain text version
 */
function stripHtml(html: string): string {
	return html
		.replace(/<style[^>]*>.*?<\/style>/gi, '')
		.replace(/<script[^>]*>.*?<\/script>/gi, '')
		.replace(/<[^>]+>/g, '')
		.replace(/\s+/g, ' ')
		.trim()
}

Implementar Lógica de Retry

A lógica de retry é essencial para lidar com falhas transitórias, como instabilidade de rede, interrupções temporárias do SMTP ou rate limiting do provedor. Implementar retentativas com backoff exponencial aumenta a probabilidade de entrega bem-sucedida, evitando carga desnecessária em sua aplicação ou serviço de e-mail. Essa abordagem é particularmente importante em ambientes de produção, onde a confiabilidade e o tratamento gracioso de falhas são críticos.

/**
 * Sends email with retry logic
 */
export async function sendEmailWithRetry(
	options: EmailOptions,
	maxRetries = 3,
	delay = 1000
): Promise<SentMessageInfo> {
	let lastError: Error | undefined;

	for (let attempt = 1; attempt <= maxRetries; attempt++) {
		try {
			return await sendEmail(options);
		} catch (err) {
			lastError = err;
			console.warn(`Email send attempt ${attempt} failed:`, err.message);

			if (attempt < maxRetries) {
				// Wait before retrying (exponential backoff)
				await new Promise(resolve => setTimeout(resolve, delay * attempt));
			}
		}
	}

	throw new EmailError(
		`Failed to send email after ${maxRetries} attempts`,
		lastError
	);
}

Considerações para Produção

A transição do desenvolvimento para a produção requer atenção cuidadosa à segurança, escalabilidade e experiência do usuário. Os sistemas de e-mail são particularmente vulneráveis a abusos e podem rapidamente se tornar gargalos se não forem adequadamente arquitetados. Esta seção aborda padrões essenciais de produção que protegem sua aplicação, mantêm a reputação de entregabilidade e garantem uma entrega confiável de e-mails em escala.

1. Limitação de Taxa

Por que a Limitação de Taxa é Importante:

Sem limitação de taxa, seu formulário de contato se torna um alvo fácil para:

Bots de spam que enviam centenas de formulários por minuto
Agentes maliciosos usando seu serviço de e-mail para enviar spam
Abuso acidental de usuários clicando repetidamente em enviar
Esgotamento de recursos sobrecarregando seu servidor SMTP

A limitação de taxa protege sua reputação de entregabilidade de e-mails. Provedores de e-mail como o Gmail rastreiam padrões de envio, e picos repentinos de volume podem marcar seu domínio como fonte de spam, fazendo com que e-mails legítimos sejam bloqueados.

Quando Implementar:

Imediatamente, em todos os formulários públicos
Antes de lançar qualquer funcionalidade de conteúdo enviado por usuários
Essencial para formulários de contato, fluxos de cadastro e redefinições de senha

Estratégia de Implementação:

Evite abusos com limitação de taxa:

// src/lib/rateLimit.server.ts

const submissionMap = new Map<string, number[]>()
const RATE_LIMIT_WINDOW = 60 * 1000 // 1 minute
const MAX_SUBMISSIONS = 3 // Max 3 submissions per minute

/**
 * Checks if IP has exceeded rate limit
 */
export function checkRateLimit(ip: string): boolean {
	const now = Date.now()
	const submissions = submissionMap.get(ip) || []

	// Remove old submissions outside the window
	const recentSubmissions = submissions.filter((time) => now - time < RATE_LIMIT_WINDOW)

	if (recentSubmissions.length >= MAX_SUBMISSIONS) {
		return false
	}

	recentSubmissions.push(now)
	submissionMap.set(ip, recentSubmissions)

	return true
}

Use nas actions:

// src/routes/contact/+page.server.ts
import type { Actions } from './$types'
import { fail } from '@sveltejs/kit'
import { checkRateLimit } from '$lib/rateLimit.server'

export const actions = {
	default: async ({ request, getClientAddress }) => {
		const ip = getClientAddress()

		if (!checkRateLimit(ip)) {
			return fail(429, {
				errors: {
					_form: ['Too many requests. Please try again later.']
				}
			})
		}

		// Continue with form processing...
	}
}

2. Sistema de Filas para Alto Volume

Por que Filas são Importantes:

Enviar e-mails de forma síncrona durante requisições HTTP cria vários problemas críticos:

Problemas de Desempenho:

Usuários aguardam de 2 a 5 segundos para conexões SMTP e entrega de e-mails
Cada falha na entrega de e-mail bloqueia a requisição do usuário
Recursos do servidor ficam presos durante operações SMTP lentas
Experiência ruim para o usuário com carregamentos de página longos

Problemas de Confiabilidade:

Timeouts de rede causam falhas no envio de formulários
Usuários veem erros mesmo quando os dados são válidos
Sem nova tentativa automática em falhas temporárias
Limites de taxa de provedores de e-mail causam falhas em cascata

Restrições de Escalabilidade:

Não é possível enviar e-mails em massa sem bloquear a aplicação
Difícil implementar filas de prioridade (urgente vs. marketing)
Sem forma de pausar/retomar o envio de e-mails
Difícil escalar o envio de e-mails independentemente dos servidores web

Quando Implementar:

Necessidade imediata (100+ e-mails/dia): Quando usuários percebem lentidão no envio de formulários
Planejar com antecedência (500+ e-mails/dia): Antes que o volume de e-mails impacte a experiência do usuário
Essencial (1000+ e-mails/dia): Quando confiabilidade e entregabilidade se tornam críticas
Crítico (10.000+ e-mails/dia): Quando você precisa de infraestrutura dedicada de e-mail

Cenários do Mundo Real:

Sequências de e-mails de boas-vindas com múltiplos pontos de contato
E-mails de resumo diário para milhares de assinantes
E-mails de redefinição de senha durante picos de tráfego
Recibos transacionais após compra
Campanhas de marketing com horários de envio precisos

Benefícios das Filas:

Feedback imediato ao usuário: O envio do formulário retorna imediatamente
Novas tentativas automáticas: E-mails com falha são reenviados com backoff exponencial
Limitação de taxa: Controle a velocidade de envio para se manter dentro dos limites do provedor
Tratamento de prioridade: Envie e-mails urgentes antes do conteúdo de marketing
Monitoramento: Acompanhe taxas de entrega, falhas e tempos de processamento
Escalabilidade: Adicione workers para processar mais e-mails em paralelo

Implementação com BullMQ e Redis:

Para aplicações que enviam muitos e-mails, use uma fila:

npm install bullmq ioredis

// src/lib/queue/emailQueue.server.ts

import { Queue, Worker } from 'bullmq'
import Redis from 'ioredis'
import { sendEmail } from '$lib/mailer/sendEmail.server'

interface EmailJob {
	to: string
	from: string
	replyTo: string
	subject: string
	html: string
}

const connection = new Redis({
	host: process.env.REDIS_HOST || 'localhost',
	port: process.env.REDIS_PORT || 6379,
	maxRetriesPerRequest: null
})

// Create email queue
export const emailQueue = new Queue('emails', { connection })

// Create worker to process emails
const worker = new Worker(
	'emails',
	async (job) => {
		const { to, from, replyTo, subject, html } = job.data
		await sendEmail({ to, from, replyTo, subject, html })
	},
	{
		connection,
		concurrency: 5, // Process 5 emails concurrently
		limiter: {
			max: 10, // Max 10 emails
			duration: 1000 // Per second
		}
	}
)

worker.on('completed', (job) => {
	console.log(`✓ Email ${job.id} sent successfully`)
})

worker.on('failed', (job, err) => {
	console.error(`✗ Email ${job.id} failed:`, err)
})

Use a fila nas actions:

// src/routes/contact/+page.server.ts
import type { Actions } from './$types';
import { emailQueue } from '$lib/queue/emailQueue.server';

export const actions = {
	default: async ({ request }) => {
		// ... validation ...

		// Add to queue instead of sending directly
		await emailQueue.add('contact-form', {
			to: GOOGLE_EMAIL,
			from: `"${data.name}" <${data.email}>`,
			replyTo: data.email,
			subject: `Contact: ${data.name}`,
			html: contactTemplate(data)
		});

		return { success: true };
	}
};

3. Monitoramento de Entrega de E-mails

Por que o Monitoramento é Importante:

A entrega de e-mails acontece de forma assíncrona em múltiplos sistemas, e falhas podem ocorrer silenciosamente sem monitoramento adequado:

Cenários de Falha Silenciosa:

O servidor SMTP aceita o e-mail, mas nunca o entrega (soft bounce)
O e-mail cai na pasta de spam (entregue, mas não visto)
O servidor do destinatário rejeita o e-mail após aceitação inicial
A inclusão em blacklists impede a entrega para provedores inteiros
A limitação de taxa causa falhas temporárias que se tornam permanentes

Impacto nos Negócios:

Receita perdida: E-mails de confirmação nunca chegam, usuários abandonam carrinhos
Carga de suporte: Usuários não recebem redefinições de senha, criam tickets duplicados
Dano à reputação: E-mails transacionais importantes vão para o spam
Risco de conformidade: Não é possível provar que notificações por e-mail foram enviadas
Pesadelo de depuração: Sem como investigar relatórios de "nunca recebi o e-mail"

O que Monitorar:

Métricas de Sucesso:

Total de e-mails enviados por hora/dia
Tempo médio de entrega
Taxa de sucesso de entrega por domínio do destinatário
Picos de envio e volumes

Rastreamento de Falhas:

Hard bounces (falhas permanentes de entrega)
Soft bounces (falhas temporárias, candidatos a nova tentativa)
Reclamações de spam e cancelamentos de assinatura
Taxas de rejeição específicas por provedor

Saúde do Sistema:

Falhas de conexão SMTP
Profundidade da fila e taxa de processamento
Tentativas de reenvio e resultados
Erros e crashes de workers

Quando Implementar:

Dia um: Log básico (enviado/falhou com messageId)
Antes do lançamento: Log em banco de dados para consultas de suporte
Pós-lançamento: Dashboard com taxas de entrega e alertas
Em escala: Monitoramento em tempo real com alertas sobre anomalias

Estratégia de Implementação:

Rastreie o status de entrega de e-mails:

// src/lib/db/emailLog.server.ts

import { db } from './database.server'

interface EmailLogData {
	to: string
	subject: string
	status: 'sent' | 'failed' | 'queued'
	messageId?: string
	error?: string
}

/**
 * Logs email send attempts
 */
export async function logEmail({
	to,
	subject,
	status,
	messageId,
	error
}: EmailLogData): Promise<void> {
	await db.emailLog.create({
		data: {
			to,
			subject,
			status, // 'sent', 'failed', 'queued'
			messageId,
			error,
			sentAt: new Date()
		}
	})
}

4. Gerenciamento de Cancelamento de Assinatura

Por que o Gerenciamento de Cancelamento de Assinatura é Importante:

A funcionalidade de cancelamento de assinatura não é apenas uma boa prática — é legalmente exigida em muitas jurisdições e crítica para manter a entregabilidade de e-mails:

Requisitos Legais:

CAN-SPAM Act (EUA): Exige link visível de cancelamento em todos os e-mails comerciais
GDPR (UE): Usuários têm direito de retirar consentimento para comunicações de marketing
CASL (Canadá): Exige mecanismo claro de cancelamento de assinatura
Penalidades: Multas de até $43.792 por violação (CAN-SPAM) ou 4% da receita (GDPR)

Impacto na Entregabilidade:

Usuários que não conseguem cancelar marcam e-mails como spam
Altas taxas de reclamação de spam (>0,1%) acionam filtros dos provedores
Gmail, Outlook filtram automaticamente domínios com experiência ruim de cancelamento
A inclusão em blacklists pode bloquear TODOS os e-mails do seu domínio

Experiência do Usuário:

Cancelamento respeitoso = percepção positiva da marca
Assinaturas forçadas = avaliações negativas e reclamações nas redes sociais
Cancelamento com um clique = menores taxas de reclamação de spam
E-mails de confirmação demonstram profissionalismo

Considerações Técnicas:

O que Constitui Marketing vs. Transacional:

Marketing (requer cancelamento de assinatura):

Atualizações de newsletter e blog
Anúncios de produtos e promoções
Convites para eventos e webinars
Destaques de funcionalidades e dicas

Transacional (cancelamento não obrigatório):

Confirmações de pedidos e recibos
E-mails de redefinição de senha
Alertas de segurança da conta
Notificações de status do serviço

Quando não está claro: Prefira incluir o cancelamento de assinatura

Requisitos de Implementação:

Link de cancelamento no rodapé de todo e-mail de marketing
Cancelamento com um clique (sem necessidade de login)
Processar cancelamentos em até 10 dias úteis (requisito legal)
Respeitar o cancelamento imediatamente (melhor prática)
Mensagem de confirmação após o cancelamento
Opção de re-assinatura para casos de engano

Design do Banco de Dados:

Armazenar timestamp do cancelamento (trilha de auditoria)
Tabela separada dos usuários (privacidade/GDPR)
Índice no e-mail para buscas rápidas
Incluir motivo do cancelamento (opcional, feedback valioso)

Melhores Práticas:

Exibir link de cancelamento de forma destacada no rodapé
Usar linguagem clara: "Cancelar assinatura" e não "Gerenciar preferências"
Não esconder atrás de múltiplos cliques
Respeitar preferências granulares (resumo semanal vs. diário)
Enviar e-mail de confirmação (prova de que o cancelamento foi feito)

Estratégia de Implementação:

Para e-mails de marketing, implemente o cancelamento de assinatura:

// src/routes/unsubscribe/+page.server.ts

import type { Actions } from './$types'
import { db } from '$lib/db'

export const actions: Actions = {
	default: async ({ request }) => {
		const formData = await request.formData()
		const email = formData.get('email')

		// Add to unsubscribe list
		await db.unsubscribed.create({
			data: {
				email: email.toLowerCase(),
				unsubscribedAt: new Date()
			}
		})

		return { success: true }
	}
}

Verifique antes de enviar:

// src/lib/mailer/sendEmail.server.ts

interface MarketingEmailContent {
	subject: string;
	html: string;
	from: string;
}

async function sendMarketingEmail(email: string, content: MarketingEmailContent): Promise<void> {
	// Check unsubscribe list
	const unsubscribed = await db.unsubscribed.findUnique({
		where: { email: email.toLowerCase() }
	});

	if (unsubscribed) {
		console.log(`Skipping unsubscribed email: ${email}`);
		return;
	}

	await sendEmail({ to: email, ...content });
}

Monitoramento Adicional:

Rastreie métricas de cancelamento para melhorar a estratégia de e-mail:

Taxa de cancelamento por campanha
Tempo para cancelar após o cadastro
Motivo do cancelamento (se coletado)
Taxa de re-assinatura

Altas taxas de cancelamento (>2%) indicam problemas de conteúdo ou frequência que precisam ser tratados.

Resumo das Considerações de Produção:

Esses quatro pilares — limitação de taxa, filas, monitoramento e gerenciamento de cancelamento de assinatura — formam a base de um sistema de e-mail pronto para produção. Implemente a limitação de taxa e o monitoramento básico desde o primeiro dia. Adicione filas antes de precisar delas (a partir de ~100 e-mails/dia). Construa a funcionalidade de cancelamento de assinatura antes de enviar qualquer e-mail de marketing. Juntos, esses padrões garantem que seu sistema de e-mail escale de forma confiável, mantendo a entregabilidade e a conformidade legal.

Boas Práticas de Segurança

1. Nunca Exponha Credenciais de E-mail

// src/lib/mailer/emailSetup.server.js
// ❌ NEVER do this
export const GMAIL_PASSWORD = 'my-password'

// ✅ Always use environment variables
import { GOOGLE_EMAIL_PASSWORD } from '$env/dynamic/private'

2. Valide e Sanitize a Entrada

// src/lib/types.js
// Use Valibot for comprehensive validation
const emailSchema = v.object({
	email: v.pipe(v.string(), v.email(), v.maxLength(254)),
	message: v.pipe(v.string(), v.nonEmpty(), v.maxLength(1000), v.trim())
})

// src/lib/mailer/templates/contact.js
// Escape HTML in email templates
function escapeHtml(text) {
	return text
		.replace(/&/g, '&amp;')
		.replace(/</g, '&lt;')
		.replace(/>/g, '&gt;')
		.replace(/"/g, '"')
		.replace(/'/g, '&#039;')
}

3. Implemente CAPTCHA

Evite envios por bots:

npm install @sveltejs/kit-turnstile

<!-- src/routes/contact/+page.svelte -->
<script>
	import { Turnstile } from '@sveltejs/kit-turnstile'

	let token = $state('')
</script>

<form method="POST">
	<!-- Form fields -->

	<Turnstile bind:token />

	<button type="submit" disabled={!token}> Send Message </button>
</form>

Verifique no servidor:

// src/routes/contact/+page.server.js
export const actions = {
	default: async ({ request, fetch }) => {
		const formData = await request.formData()
		const token = formData.get('cf-turnstile-response')

		// Verify CAPTCHA
		const verification = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify({
				secret: process.env.TURNSTILE_SECRET_KEY,
				response: token
			})
		})

		const outcome = await verification.json()
		if (!outcome.success) {
			return fail(400, {
				errors: { _form: ['CAPTCHA verification failed'] }
			})
		}

		// Process form...
	}
}

Depurando Problemas Comuns

Causa: Credenciais incorretas ou senha de aplicativo não habilitada

Solução:

Ative a verificação em duas etapas na conta Google
Gere uma senha específica para o aplicativo
Use a senha do aplicativo no arquivo .env

2: E-mails indo para o spam

Soluções:

Use um domínio de remetente verificado
Adicione registros SPF, DKIM e DMARC
Evite palavras que acionam filtros de spam
Inclua link de cancelamento de assinatura
Use um serviço SMTP de reputação confiável

3: Erro "ECONNREFUSED"

Causa: Não é possível conectar ao servidor SMTP

Solução:

// src/lib/mailer/emailSetup.server.js
// Add connection verification
transporter.verify((error, success) => {
	if (error) {
		console.error('SMTP connection failed:', error)
		console.log('Check:')
		console.log('- SMTP host and port')
		console.log('- Firewall settings')
		console.log('- Network connectivity')
	} else {
		console.log('✓ SMTP connection successful')
	}
})

4: Formulário não enviando

Verifique:

method="POST" no formulário
URL da action correta
use:enhance de $app/forms
Console do navegador para erros

Exemplo Completo Funcional

Aqui está tudo junto em uma implementação pronta para produção:

Estrutura do Projeto

src/
├── lib/
│   ├── mailer/
│   │   ├── emailSetup.server.js
│   │   ├── sendEmail.server.js
│   │   └── templates/
│   │       ├── layout.js
│   │       └── contact.js
│   ├── types.js
│   └── rateLimit.server.js
├── routes/
│   └── contact/
│       ├── +page.svelte
│       └── +page.server.js
└── app.html

Configuração do Ambiente

# .env
GOOGLE_EMAIL="your-email@gmail.com"
GOOGLE_EMAIL_PASSWORD="your-app-password"

Implementação Completa

Todo o código fornecido acima funciona em conjunto. Para resumir o fluxo:

Usuário preenche o formulário em +page.svelte
Formulário é enviado para a action em +page.server.js
A action valida com Valibot
O e-mail é enviado via transporter do Nodemailer
A resposta retorna ao componente
O componente exibe mensagens de sucesso/erro

Conclusão

Agora você tem uma compreensão completa de como implementar funcionalidade de e-mail no SvelteKit com Nodemailer. Principais aprendizados:

Segurança no Servidor: A lógica de e-mail executa apenas no lado do servidor
Aprimoramento Progressivo: Formulários funcionam sem JavaScript
Padrões Modernos: Runes do Svelte 5 e $props()
Segurança de Tipos: TypeScript e validação com Valibot
Leveza: Pequeno tamanho de bundle do Valibot
Escalabilidade: Sistemas de filas para alto volume
Segurança: Limitação de taxa, CAPTCHA e sanitização

Próximos Passos

Implementar fluxos de confirmação por e-mail
Adicionar suporte a anexos de arquivos
Criar sistema de notificação por e-mail
Construir assinatura de newsletter
Implementar e-mails transacionais

Recursos Adicionais

Para guias e tutoriais mais aprofundados

Templates de E-mail Avançados

Documentação:

Serviços de E-mail:

SendPigeon - E-mail transacional moderno para desenvolvedores
SendGrid - Entrega de e-mail baseada em nuvem
Mailgun - Serviço de API de e-mail
Amazon SES - Infraestrutura de e-mail da AWS

Ferramentas de Teste:

Ethereal Email - Serviço SMTP falso gratuito
Mailpit - Servidor SMTP local moderno
MailCrab - Teste de e-mail leve em Rust
smtp4dev - Servidor de teste de e-mail .NET
SendPigeon Local Server - Teste de e-mail para SvelteKit

Teste de E-mail:

Email on Acid - Teste de renderização de e-mail

Este guia foca em implementações práticas e prontas para produção usando padrões modernos do Svelte 5 e validação com Valibot. Para mais tutoriais, visite The Hackpile Chronicles.

Introdução

O que é o Nodemailer?

O que Você vai Aprender

Pré-requisitos

Configuração do Projeto

Configuração de Ambiente

1. Criar as Variáveis de Ambiente

2. Atualizar o .gitignore

3. Criar o .env.example

Configurando o Transporter de Email

Entendendo a Convenção .server.js

Criar a Configuração de Email

Alternativa: Usando Outros Serviços de Email

SendGrid

Mailgun

AWS SES

SendPigeon

Opinião: Por que Começar com Nodemailer no Svelte 5

Construindo o Componente de Formulário de Contato

Criar o Componente de Formulário

Validação

Por que Valibot?

Criar Schema de Validação

Actions no Servidor

Entendendo as Actions de Formulário

Criar a Action Padrão

Conceitos-Chave Explicados

1. A Função fail

2. Métodos do FormData

3. Tratamento de Erros do Valibot

4. Segurança em E-mails HTML

É tudo que você precisa... mais ou menos

Entendendo as Actions de Formulário: Do Simples ao Avançado

Comece Aqui: O Padrão de Action Única

Por que Isso Funciona

Quando Você Precisa de Múltiplas Actions

Reconhecendo o Padrão

Construindo o Entendimento: O Exemplo do Recibo

O Lado do Servidor

Entendendo formaction

Equívocos Comuns

1: Múltiplos departamentos precisam de múltiplas actions

2: Teste vs Produção = Múltiplas actions

Framework de Decisão

Testando Seu Entendimento

Resumo: O Padrão Certo para Sua Situação

Use Action Única (Padrão) Quando:

Use Named Actions Quando:

Evite Múltiplas Actions Quando:

Testando a Funcionalidade de E-mail

1. Ethereal Email (Recomendado para Testes Rápidos)

Como funciona

2. Mailpit (Servidor SMTP Local Moderno)

3. MailCrab (Alternativa Leve em Rust)

4. smtp4dev (Multiplataforma com Docker)

5. SendPigeon Local Dev Server

Tabela Comparativa

Recomendações

6. Estratégia Abrangente de Testes

6.1 Testes Unitários de Form Actions

6.2 Testes de Integração com Serviços de E-mail

6.3 Testando Templates de E-mail

6.4 Fazendo Mock de Serviços de E-mail

6.5 Testes End-to-End com Playwright

6.6 Integração com CI/CD

6.7 Boas Práticas de Testes

Tratamento de Erros e Logging

Implementar Lógica de Retry

Considerações para Produção

1. Limitação de Taxa

2. Sistema de Filas para Alto Volume

3. Monitoramento de Entrega de E-mails

4. Gerenciamento de Cancelamento de Assinatura

Boas Práticas de Segurança

1. Nunca Exponha Credenciais de E-mail

2. Valide e Sanitize a Entrada

3. Implemente CAPTCHA

Depurando Problemas Comuns

1: "Invalid login: 535 Authentication failed"

2: E-mails indo para o spam

1. A Função `fail`