Introdução

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

O que é o Nodemailer?

Nodemailer é um módulo Node.js que simplifica o envio de e-mails. Ele suporta diversos métodos de transporte (SMTP, Gmail, SendGrid, etc.) e cuida da complexidade dos protocolos de e-mail para você. No contexto do SvelteKit, o Nodemailer é executado exclusivamente no servidor, mantendo as credenciais sensíveis seguras.

O que Você Aprenderá

Ao final deste guia, você entenderá:

Como configurar o Nodemailer com variáveis de ambiente
Como criar handlers de e-mail 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 e-mail com actions nomeadas
Como gerenciar estado de formulário e tratamento de erros
Implementações type-safe com TypeScript

Pré-requisitos

Conhecimento básico de roteamento e form actions no SvelteKit
Node.js instalado (v18 ou superior 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 e-mail jamais devem ser inseridas diretamente no código. O SvelteKit fornece módulos de variáveis de ambiente para segredos exclusivos 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 as 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. Melhor para deployments 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 é no desenvolvimento local, onde você deseja que as alterações no .env entrem em vigor ao reiniciar o servidor de desenvolvimento sem precisar reconstruir. Ao fazer deploy em produção, considere $env/static/private se sua plataforma suportar variáveis de ambiente em tempo de build para melhor desempenho.

1. Criar 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 Transportador de E-mail

O transportador é sua conexão com o serviço de e-mail. Vamos criar um módulo reutilizável exclusivo do 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 E-mail

// 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 E-mail

O Nodemailer suporta diversos serviços. Aqui estão as alternativas mais comuns:

SendGrid

SendGrid é um popular serviço de entrega de e-mail 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 e-mail 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 e-mail 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 e-mail 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 e-mail local gratuito para testes
Construtor de e-mail 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 conveniência e praticidade, o Nodemailer continua sendo a melhor base para aprender e-mail em projetos SvelteKit.

Por que Nodemailer Primeiro:

Compreensão em vez de Abstração: O Nodemailer te obriga a entender como o e-mail 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 se integra perfeitamente com servidores SMTP locais (Mailpit, MailCrab, smtp4dev) e Ethereal Email. Você pode testar fluxos de e-mail completos 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 e-mail 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 e-mail personalizado é apenas uma questão de configuração. Soluções baseadas em API te prendem ao ecossistema delas.
Escalabilidade em Produção: O Nodemailer escala desde formulários de contato simples até e-mails transacionais em nível empresarial sem mudanças arquiteturais. Sistemas de fila (BullMQ) e pool de conexões funcionam da mesma forma, seja enviando 10 ou 10.000 e-mails 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 em vez de caixas-pretas.
Para recursos específicos: Análises de e-mail, testes A/B, sistemas de templates avançados e otimização dedicada de entregabilidade justificam as trocas do lock-in de fornecedor.
Em grande escala: Quando você está enviando milhões de e-mails por mês, serviços gerenciados oferecem infraestrutura que você não quer manter sozinho.

O Caminho de Aprendizado:

Comece aqui: Domine o Nodemailer + ferramentas de teste local
Adicione preocupações de produção: Sistemas de fila, monitoramento, limitação de taxa
Depois 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 trocas intencionais, não substituições. Aprenda os fundamentos com o Nodemailer primeiro e, em seguida, 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.

Usaremos a action enhance de $app/forms para lidar com envios de formulário sem JavaScript, mantendo ainda uma experiência fluida quando o JavaScript estiver 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 é totalmente funcional com aprimoramento progressivo. Ele funcionará sem JavaScript, pois o formulário ainda opera por meio do envio HTML nativo, mas com JavaScript você obtém:

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

Validação

Antes de enviar e-mails, 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 é ~14KB)
Tree-Shakeable: Empacote apenas o que você usa
Segurança de Tipos: Integração completa com TypeScript
Combiná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 processemos apenas dados válidos e forneceremos mensagens de erro significativas 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 do 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 do lado do 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 (aprimoramento progressivo)

Criar a Action Padrão

O SvelteKit permite que você defina uma action padrão 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 limites de erro:

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 prevenir 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 todas as etapas necessárias—incluindo a configuração correta de uma Senha de App do Google—essa configuração é tudo que você precisa. Os envios de formulários devem enviar e-mails com sucesso para o endereço designado.

Neste ponto, você terminou. Sério. Se esse é o seu caso de uso, você pode parar aqui e publicar.

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

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

Uma vez que o básico esteja consolidado e você esteja confiante de que tudo funciona de ponta a ponta, você estará pronto para ir mais fundo.

Vamos avançar mais.

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

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

A resposta depende de quem está tomando a decisão e qual 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 do servidor lida com toda a lógica de e-mail em um só 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, 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 de prioridade?"

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

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

✅ Usuários não podem cometer erros (sem botão errado para clicar)
✅ Você controla o fluxo de e-mail centralmente
✅ Fácil de adicionar limitação de taxa, validação e registro
✅ Simples de testar e manter
✅ Funciona sem JavaScript (aprimoramento progressivo)

Se esse padrão resolve o seu problema, você terminou. Publique. 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 actions nomeadas se tornam úteis.

Reconhecendo o Padrão

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

Exemplos onde usuários fazem escolhas:

Cenário	Decisão do Usuário	Resultado do E-mail
Enviar recibo	"Enviar só para o cliente" vs "Enviar + manter 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 usuários NÃO fazem escolhas:

Cenário	O que Realmente Acontece	Padrão Correto
Formulário de contato	Sempre notifica o admin + confirma para o usuário	Action única, múltiplos e-mails
Cadastro na newsletter	Sempre confirma + notifica a equipe	Action única, múltiplos e-mails
Recibo de pedido	Sempre envia e-mail para 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ê administra 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 ramificada.

A abordagem correta com actions nomeadas:

<!-- ✅ 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>

Perceba o atributo formaction? Ele diz ao navegador qual action do servidor chamar. Sem necessidade de roteamento com 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 lado do servidor
Intenção explícita: O nome da action documenta o que acontece
Fácil de testar: Teste cada action de forma independente

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 actions no servidor:

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 não 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
A estrutura da sua organização 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 da aplicação?"
- Entrega de e-mail → Named actions
- Lógica da aplicação → Tratar no lado do servidor
"Um usuário poderia acidentalmente escolher a opção errada?"
- Se SIM → Abstração errada, simplifique

Testando Seu Entendimento

Antes de continuar, tente responder estas questões:

Cenário 1: Você tem um formulário "Reportar Bug". Os usuários deveriam 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 menu suspenso 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ê deveria 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 envia para ambos
Se a contabilidade precisa APENAS às vezes → Named actions faz sentido
Se você não tem certeza → Comece com action única (sempre envia para ambos), pode refatorar depois

A pergunta-chave: "O contador precisa de TODA fatura, ou apenas de 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 que sua equipe recebe uma notificação é 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 uma escolha do usuário
✅ Você não tem certeza de qual padrão usar (comece simples!)

Exemplo: Formulários de contato, inscrições em newsletters, confirmações de pedidos

Use Named Actions Quando:

✅ O usuário escolhe conscientemente entre diferentes resultados
✅ A escolha altera o comportamento do e-mail (destinatários, tempo, 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/depuração
❌ A "escolha" é na verdade apenas um parâmetro

Solução: Trate o roteamento no lado do 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 sendo 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 sua aplicação em modo de desenvolvimento. Quando você envia um e-mail, o Ethereal registra uma URL de pré-visualização no console. Clique na URL para visualizar o e-mail na interface web do Ethereal.

Execute sua aplicação SvelteKit em modo de desenvolvimento
Preencha o formulário de contato e envie
Verifique o terminal para 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é-visualização é registrada, permitindo que você visualize cada e-mail separadamente. As contas expiram após 24 horas, garantindo um ambiente de teste limpo e sem acúmulo.

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 ou menos detalhes aqui?

Além disso, percebo que as outras ferramentas de teste (Mailpit, MailCrab, etc.) têm o mesmo problema - elas mostram a instalação, mas não os passos de "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 o transporter:

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

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

Visualize emails em http://localhost:8025

Recursos:

UI moderna e responsiva
Busca e filtragem
Pré-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 email 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 o transporter:

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

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

Visualize emails 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
Compatível com dispositivos móveis
Sem dependências

4. smtp4dev (Multiplataforma com Docker)

smtp4dev é um servidor de teste de email moderno e ativamente mantido, com excelente suporte a Docker. Ele roda 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 o transporter:

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

Visualize emails em http://localhost:3000

Recursos:

UI moderna e elegante
Editar e reenviar emails
Suporte a relay SMTP
Suporte a Docker
Multiplataforma (.NET)
Acesso via API

5. SendPigeon Local Dev Server

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

# Install SendPigeon CLI
npm install -g sendpigeon

# Start local dev server
sendpigeon dev

Configure para testes:

// 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
	})
}

Visualize emails em http://localhost:3005

Recursos:

Desenvolvido especificamente para SvelteKit
Captura automática de emails
Pré-visualização visual de emails
Sem necessidade de configuração SMTP
Suporte a TypeScript
Teste de webhooks
Gratuito e open source

Tabela Comparativa

Ferramenta	Porta SMTP	Porta Web	Instalação	Ideal 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 com recursos completos
CI/CD: Use o Ethereal para testes automatizados
Configuração Mínima: Use o MailCrab se quiser algo leve
Projetos Docker: Use o smtp4dev para fluxos de trabalho em contêineres

Em resumo, todas essas ferramentas resolvem o mesmo problema central — testes seguros de email — mas se destacam em cenários diferentes, e essa distinção importa 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 de cabeçalhos, corpos e anexos, e se integram perfeitamente ao Nodemailer apenas alterando host e 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.

Recorra ao 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 onde o envio de emails está fortemente acoplado à lógica de negócios.

O principal aprendizado:

- Coletores SMTP locais são melhores para controle, realismo e reprodutibilidade.
- O Ethereal é melhor para testes rápidos e descartáveis.
- O SendPigeon é melhor quando minimizar a diferença 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 emails, mas o que mantém seu ciclo de feedback rápido, seguro e previsível.

6. Estratégia Abrangente de Testes

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

6.1 Testando Form Actions com Testes Unitários

Comece testando suas form actions de forma isolada. Concentre-se na validação, no tratamento de erros e na 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 Email

Teste a funcionalidade real de envio de emails usando seu servidor SMTP de testes:

// 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 Email

Garanta que seus templates de email sejam renderizados corretamente e lidem com 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 Mockando Serviços de Email

Use mocks para evitar o envio real de emails 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 o mock nos seus testes:

// 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 no 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 de forma abrangente
✅ Mockar serviços de email 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 email são renderizados corretamente
✅ Testar o tratamento de erros e a lógica de retry
✅ Incluir testes E2E para fluxos críticos de usuário

O que não fazer:

❌ Enviar emails reais em testes automatizados
❌ Codificar credenciais de teste diretamente no código
❌ Ignorar o teste de casos extremos em templates de email
❌ 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 email: 90%+
Renderização de templates: 90%+
Caminhos críticos E2E: 100%

Tratamento de Erros e Logging

Ao enviar emails, o tratamento robusto de erros é essencial para garantir que os problemas sejam detectados e resolvidos prontamente. Esta seção aborda boas práticas de 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 retries com backoff exponencial aumenta a probabilidade de entrega bem-sucedida, evitando carga desnecessária na sua aplicação ou serviço de email. Essa abordagem é particularmente importante em ambientes de produção, onde confiabilidade e 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 consideração cuidadosa de segurança, escalabilidade e experiência do usuário. Sistemas de email são particularmente vulneráveis a abusos e podem rapidamente se tornar gargalos se não forem arquitetados adequadamente. Esta seção aborda padrões essenciais de produção que protegem sua aplicação, mantêm a reputação de entregabilidade e garantem o envio confiável de emails 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-mail. Provedores de e-mail como o Gmail rastreiam padrões de envio, e picos repentinos de volume podem sinalizar seu domínio como uma 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 recurso 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:

Previna 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 Fila 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-mail
Cada falha na entrega de e-mail bloqueia a requisição do usuário
Recursos do servidor ficam ocupados durante operações SMTP lentas
Experiência ruim do usuário com carregamentos de página demorados

Problemas de Confiabilidade:

Timeouts de rede causam falhas nos envios de formulários
Usuários veem erros mesmo que seus dados sejam válidos
Sem tentativas automáticas em falhas temporárias
Limites de taxa do provedor 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 envios de formulário lentos
Planeje 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-mail 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 de transações após compras
Campanhas de marketing com horários de envio precisos

Benefícios da Fila:

Feedback instantâneo ao usuário: Envios de formulário retornam imediatamente
Tentativas automáticas: E-mails com falha são reenviados com backoff exponencial
Limitação de taxa: Controle a velocidade de envio para permanecer 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-mail

Por Que o Monitoramento É Importante:

A entrega de e-mail 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 a aceitação inicial
O blacklisting de domínio impede a entrega para provedores inteiros
A limitação de taxa causa falhas temporárias que se tornam permanentes

Impacto nos Negócios:

Perda de receita: E-mails de confirmação nunca chegam, usuários abandonam carrinhos
Sobrecarga de suporte: Usuários não recebem redefinições de senha, criam tickets duplicados
Danos à reputação: E-mails transacionais importantes vão para spam
Risco de conformidade: Impossí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
Horários e volumes de pico de envio

Rastreamento de Falhas:

Hard bounces (falhas permanentes de entrega)
Soft bounces (falhas temporárias, candidatos a reenvio)
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 falhas 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:

Acompanhe o status de entrega de e-mail:

// 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 obrigatória em muitas jurisdições e crítica para manter a entregabilidade de e-mail:

Requisitos Legais:

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

Impacto na Entregabilidade:

Usuários que não conseguem cancelar a assinatura marcam e-mails como spam
Altas taxas de reclamação de spam (>0,1%) acionam filtragem do provedor
Gmail e Outlook filtram automaticamente domínios com má experiência de cancelamento
O blacklisting 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):

Boletins informativos e atualizações de blog
Anúncios de produtos e promoções
Convites para eventos e webinars
Destaques de funcionalidades e dicas

Transacional (cancelamento de assinatura 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 estiver claro: Prefira incluir o cancelamento de assinatura

Requisitos de Implementação:

Link de cancelamento no rodapé de todos os e-mails 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 reinscrição para erros

Design do Banco de Dados:

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

Melhores Práticas:

Exibir o 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 (comprova 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:

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

Taxa de cancelamento por campanha
Tempo até o cancelamento após o cadastro
Motivo do cancelamento (se coletado)
Taxa de reinscrição

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

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

Estes 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 limitação de taxa e monitoramento básico desde o primeiro dia. Adicione filas antes de precisar delas (em ~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.

Melhores 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

Previna 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:

Habilite a autenticação em dois fatores na conta do Google
Gere uma senha específica para o aplicativo
Use a senha do aplicativo no arquivo .env

2: E-mails indo para spam

Soluções:

Use um domínio de remetente verificado
Adicione registros SPF, DKIM e DMARC
Evite palavras que ativam filtros de spam
Inclua link de cancelamento de assinatura
Use um serviço SMTP 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 envia para a action em +page.server.js
A action valida com Valibot
O e-mail é enviado via transporter do Nodemailer
A resposta retorna para o componente
O componente exibe mensagens de sucesso/erro

Conclusão

Agora você tem um entendimento completo de como implementar funcionalidade de e-mail no SvelteKit com Nodemailer. Principais aprendizados:

Segurança no Servidor: A lógica de e-mail é executada somente 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 fila para alto volume
Segurança: Limitação de taxa, CAPTCHA e sanitização

Próximos Passos

Implementar fluxos de confirmação de e-mail
Adicionar suporte a anexos de arquivos
Criar sistema de notificações 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

Testes 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ê Aprenderá

Pré-requisitos

Configuração do Projeto

Configuração de Ambiente

1. Criar Variáveis de Ambiente

2. Atualizar o .gitignore

3. Criar o .env.example

Configurando o Transportador de E-mail

Entendendo a Convenção .server.js

Criar a Configuração de E-mail

Alternativa: Usando Outros Serviços de E-mail

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 do 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 Testando Form Actions com Testes Unitários

6.2 Testes de Integração com Serviços de Email

6.3 Testando Templates de Email

6.4 Mockando Serviços de Email

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 Fila para Alto Volume

3. Monitoramento de Entrega de E-mail

4. Gerenciamento de Cancelamento de Assinatura

Melhores 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 spam

1. A Função `fail`