Introducción

La funcionalidad de email es una piedra angular de las aplicaciones web modernas. Ya sea que estés construyendo un formulario de contacto, un sistema de autenticación de usuarios o un servicio de notificaciones, entender cómo manejar el email del lado del servidor es esencial. Esta guía recorre la implementación de funcionalidad de email en SvelteKit usando Nodemailer, enfocándose en los patrones modernos de Svelte 5 y las buenas prácticas.

¿Qué es Nodemailer?

Nodemailer es un módulo de Node.js que hace que el envío de emails sea sencillo. Soporta varios métodos de transporte (SMTP, Gmail, SendGrid, etc.) y maneja la complejidad de los protocolos de email por ti. En un contexto de SvelteKit, Nodemailer se ejecuta exclusivamente en el servidor, manteniendo seguros las credenciales sensibles.

Qué Aprenderás

Al final de esta guía, entenderás:

Cómo configurar Nodemailer con variables de entorno
Cómo crear manejadores de email del lado del servidor
Cómo construir formularios con mejora progresiva en Svelte 5
Cómo implementar validación de formularios con Valibot
Cómo manejar múltiples destinos de email con named actions
Cómo gestionar el estado del formulario y el manejo de errores
Implementaciones con tipos seguros usando TypeScript

Prerrequisitos

Comprensión básica del enrutamiento de SvelteKit y las form actions
Node.js instalado (v18 o posterior recomendado)
Una cuenta de Gmail o un servicio SMTP para pruebas

Configuración del Proyecto

Primero, instala las dependencias requeridas:

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

Configuración de Variables de Entorno

Las credenciales de email nunca deben estar hardcodeadas. SvelteKit provee módulos de variables de entorno solo para el servidor que nunca se exponen al cliente.

Entendiendo las Variables de Entorno de SvelteKit:

SvelteKit ofrece dos tipos de variables de entorno privadas:

$env/dynamic/private - Se leen en tiempo de ejecución desde archivos .env. Perfectas para el desarrollo local y cuando las variables de entorno se inyectan al arrancar el contenedor/servidor. Los valores pueden cambiar sin necesidad de reconstruir.
$env/static/private - Se reemplazan en tiempo de compilación como literales de cadena. Ideales para despliegues serverless (Vercel, Netlify) donde las variables de entorno se conocen durante la compilación. Habilita el tree-shaking y un mejor rendimiento.

Usamos $env/dynamic/private ya que estamos enfocados en el desarrollo local, donde querás que los cambios en .env tomen efecto al reiniciar el servidor de desarrollo sin necesidad de reconstruir. Al desplegar a producción, considera $env/static/private si tu plataforma soporta variables de entorno en tiempo de compilación para un mejor rendimiento.

1. Crear Variables de Entorno

Crea un archivo .env en la raíz de tu proyecto:

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

Importante: Para Gmail, necesitas una Contraseña de Aplicación, no tu contraseña habitual. Habilita la verificación en dos pasos en tu cuenta de Google y luego genera una contraseña específica para la aplicación.

2. Actualizar .gitignore

Asegúrate de que tu archivo .env nunca sea commiteado:

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

3. Crear .env.example

Provee una plantilla para otros desarrolladores:

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

Configurando el Transporter de Email

El transporter es tu conexión al servicio de email. Crearemos un módulo reutilizable del lado del servidor.

Entendiendo la Convención .server.js

Los archivos que terminan en .server.js son la forma que tiene SvelteKit de declarar módulos exclusivos del servidor. Nunca pueden ser importados en código del lado del cliente, lo que provee una capa de seguridad adicional para operaciones sensibles.

Crear la Configuración 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: Usar Otros Servicios de Email

Nodemailer soporta varios servicios. Aquí hay algunas alternativas comunes:

SendGrid

SendGrid es un popular servicio de entrega de email basado en la nube:

// 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 ofrece potentes APIs de email y servicios 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 provee una infraestructura de email escalable y rentable:

// 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) es un servicio moderno de email transaccional diseñado para desarrolladores:

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

Características:

Excelente integración con SvelteKit
Soporte para TypeScript
99.9% de entregabilidad
Servidor de email local gratuito para pruebas
Constructor de emails drag-and-drop gratuito

Opinión: Por Qué Empezar con Nodemailer en Svelte 5

Si bien los servicios basados en API como SendGrid, Mailgun y SendPigeon ofrecen conveniencia y pulido, Nodemailer sigue siendo la mejor línea de base para aprender email en proyectos SvelteKit.

Por Qué Nodemailer Primero:

Comprensión Antes que Abstracción: Nodemailer te obliga a entender cómo funciona el email realmente—conexiones SMTP, estructura de mensajes, encabezados, autenticación. Los servicios basados en API abstraen todo esto, lo cual es conveniente pero deja vacíos en tu modelo mental cuando algo sale mal.
Integración para Pruebas Locales: Nodemailer se integra perfectamente con servidores SMTP locales (Mailpit, MailCrab, smtp4dev) y Ethereal Email. Puedes probar flujos completos de email sin conexión, sin claves de API, límites de velocidad ni dependencias externas. Esto hace el desarrollo más rápido y confiable.
Consistencia en la Arquitectura: Con Nodemailer, tu arquitectura de email no cambia entre desarrollo y producción—simplemente intercambias las credenciales SMTP. Los servicios basados en API suelen requerir diferentes patrones de código para pruebas vs. producción, añadiendo complejidad.
Sin Dependencia de Proveedor: Nodemailer funciona con cualquier proveedor SMTP. Una vez que lo entiendes, cambiar entre Gmail, SendGrid, AWS SES o un servidor de correo propio es solo cuestión de configuración. Las soluciones basadas en API te encierran en su ecosistema.
Escalabilidad en Producción: Nodemailer escala desde formularios de contacto simples hasta email transaccional a nivel empresarial sin cambios arquitectónicos. Los sistemas de colas (BullMQ) y el connection pooling funcionan igual ya sea que estés enviando 10 o 10,000 emails por día.

Cuándo Considerar Alternativas Basadas en API:

Después de dominar los fundamentos: Una vez que entiendas SMTP, la estructura de mensajes y la entregabilidad, los servicios basados en API se convierten en herramientas de productividad valiosas en lugar de cajas negras.
Para características específicas: El análisis de emails, las pruebas A/B, los sistemas avanzados de plantillas y la optimización dedicada de entregabilidad justifican los trade-offs del vendor lock-in.
A escala significativa: Cuando estás enviando millones de emails por mes, los servicios administrados ofrecen una infraestructura que no querrás mantener tú mismo.

El Camino de Aprendizaje:

Empieza aquí: Domina Nodemailer + herramientas de prueba locales
Agrega preocupaciones de producción: Sistemas de colas, monitoreo, rate limiting
Luego optimiza: Considera servicios basados en API cuando la conveniencia supere el costo de la abstracción

Las alternativas basadas en API son excelentes—pero son trade-offs intencionales, no reemplazos. Aprende los fundamentos con Nodemailer primero, luego elige la herramienta adecuada para tus necesidades específicas.

Construyendo el Componente de Formulario de Contacto

Vamos a crear un formulario de contacto con mejora progresiva usando los patrones modernos de Svelte 5.

Usaremos la acción enhance de $app/forms para manejar el envío de formularios sin JavaScript, mientras seguimos proporcionando una experiencia fluida cuando JavaScript está disponible.

Crear el Componente de Formulario

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

Ahora el formulario es completamente funcional con mejora progresiva. Funcionará sin JavaScript, ya que el formulario sigue funcionando a través del envío nativo de formularios HTML, pero con JavaScript obtienes:

Sin recarga completa de la página
Estados de carga
Actualizaciones optimistas de la UI
Manejo de errores

Validación

Antes de enviar emails, debemos validar la entrada del usuario. Si bien existen otras bibliotecas de validación como Zod, usamos Valibot que proporciona seguridad de tipos en tiempo de ejecución con excelente tree-shaking y cuenta con soporte oficial de Svelte.

¿Por qué Valibot?

Ligero: ~1-2KB minificado (Zod pesa ~14KB)
Tree-Shakeable: Solo incluye lo que usas
Seguridad de tipos: Integración completa con TypeScript
Componible: Encadena múltiples validaciones
Soporte oficial: Recomendado por el equipo de Svelte
API moderna: Enfoque funcional y limpio

Crear el esquema de validación

Vamos a crear un esquema de validación para los datos de nuestro formulario de contacto. Esto garantizará que solo procesemos datos válidos y que proporcionemos mensajes de error significativos a los usuarios.

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

Acciones del lado del servidor

Las acciones de formulario son la forma preferida de SvelteKit para manejar el envío de formularios. Se ejecutan en el servidor, manteniendo las operaciones sensibles de forma segura.

Entendiendo las acciones de formulario

Las acciones de formulario son funciones del lado del servidor que:

Reciben solicitudes POST de los formularios
Procesan FormData
Pueden validar, transformar y almacenar datos
Devuelven datos al cliente
Funcionan sin JavaScript (mejora progresiva)

Crear la acción predeterminada

SvelteKit te permite definir una acción predeterminada que se ejecuta cuando se envía un formulario sin un parámetro action explícito. Esto es ideal para nuestro formulario de contacto.

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

Conceptos clave explicados

1. La función `fail`

La función fail de SvelteKit devuelve errores sin activar los límites de error:

import { fail } from '@sveltejs/kit'

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

Sin fail, devolver errores activaría la página de error.

2. Métodos de `FormData`

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

3. Manejo de errores con 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. Seguridad en correos HTML

Siempre escapa la entrada del usuario en los correos HTML para prevenir ataques XSS:

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

Eso es todo lo que necesitas... más o menos

Si tu página contiene un único formulario y has completado todos los pasos requeridos —incluyendo configurar correctamente una Contraseña de Aplicación de Google— esta configuración es todo lo que necesitas. Los envíos del formulario deberían enviar correos electrónicos exitosamente a tu dirección designada.

En este punto, has terminado. En serio. Si ese es tu caso de uso, puedes detenerte aquí y publicarlo.

Dicho esto, los proyectos reales rara vez se mantienen simples para siempre. Si necesitas manejar escenarios más avanzados —múltiples formularios, diferentes destinos de correo, o flujos de trabajo más estructurados— sigue leyendo.

Antes de adentrarnos en los patrones avanzados, asegúrate de que los fundamentos sean sólidos. Prueba tu formulario usando uno de los proveedores de prueba de correo recomendados, verifica que los correos se estén enviando correctamente y confirma que la validación se comporta exactamente como se espera. Depurar lógica "avanzada" sobre una base que no funciona es una pérdida de tiempo.

Una vez que lo básico esté bien establecido y tengas confianza de que todo funciona de extremo a extremo, estarás listo para profundizar.

Llevémoslo más lejos.

Entendiendo las acciones de formulario: de lo simple a lo avanzado

Cuando estás aprendiendo la funcionalidad de correo con Nodemailer, surge frecuentemente una pregunta: "¿Mi formulario debería tener un botón de envío o varios?"

La respuesta depende de quién toma la decisión y qué decisión está tomando. Vamos a construir tu comprensión paso a paso.

Empieza aquí: el patrón de acción única

La mayoría de las aplicaciones —incluyendo la tuya— deberían comenzar con el patrón más simple: un formulario, una acción, un botón.

Así es como se ve un formulario de contacto listo para producción:

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

La acción del servidor maneja toda la lógica de correo en un solo 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' })
		}
	}
}

Observa lo que está ocurriendo aquí:

El usuario ve un botón → El servidor envía dos correos → Ambos tienen éxito o ambos fallan juntos.

Este es el patrón correcto para el 95% de las aplicaciones.

Por qué esto funciona

Piensa en el modelo mental del usuario. Cuando alguien llena un formulario de contacto, está pensando:

"Quiero enviar un mensaje"

No está pensando:

"¿Debería notificar al administrador o al equipo de ventas?"
"¿Quiero recibir un correo de confirmación?"
"¿Debería ir a la cola de prioridad?"

Esas son tus preocupaciones como desarrollador, no las del usuario. Manéjalas del lado del servidor, donde corresponden.

Beneficios de los formularios de acción única:

✅ Los usuarios no pueden cometer errores (no hay un botón equivocado para presionar)
✅ Controlas el flujo de correo de forma centralizada
✅ Fácil de agregar limitación de tasa, validación y registro
✅ Simple de probar y mantener
✅ Funciona sin JavaScript (mejora progresiva)

Si este patrón resuelve tu problema, has terminado. Publícalo. Los patrones a continuación son para escenarios más avanzados.

Cuándo necesitas múltiples acciones

A veces los usuarios genuinamente necesitan elegir qué sucede con sus datos. Aquí es donde las acciones con nombre se vuelven útiles.

Reconociendo el patrón

Pregúntate: "¿El usuario está tomando una decisión consciente sobre el resultado?"

Ejemplos donde los usuarios toman decisiones:

Escenario	Decisión del usuario	Resultado del correo
Enviar recibo	"Solo enviar al cliente" vs "Enviar + guardar una copia"	Diferente comportamiento de BCC
Formulario contacto	"Enviar ahora" vs "Guardar borrador"	Correo vs sin correo
Flujo de aprobación	"Aprobar" vs "Solicitar cambios"	Diferentes plantillas de correo

Ejemplos donde los usuarios NO toman decisiones:

Escenario	Lo que realmente ocurre	Patrón correcto
Formulario contacto	Siempre notifica al admin + confirma al usuario	Acción única, múltiples correos
Suscripción boletín	Siempre confirma + notifica al equipo	Acción única, múltiples correos
Recibo de pedido	Siempre envía correo al cliente + contabilidad	Acción única, múltiples correos

La distinción clave: ¿Es el usuario quien decide el resultado, o es el sistema el que sigue reglas?

Construyendo comprensión: el ejemplo del recibo

Exploremos un escenario real donde múltiples acciones tienen sentido.

La situación: Administras una tienda de comercio electrónico. Después de un pedido, necesitas enviar el recibo por correo al cliente. A veces quieres una copia para tus registros, a veces no.

El enfoque incorrecto:

<!-- ❌ 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 qué está mal? Estás usando una acción pero intentando manejar dos comportamientos diferentes. El servidor necesita verificar if (sendCopy) { ... }, lo que crea lógica con bifurcaciones.

El enfoque correcto con acciones con nombre:

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

¿Notas el atributo formaction? Le indica al navegador qué acción del servidor invocar. No se necesita enrutamiento con JavaScript.

El lado del servidor

Cada acción es enfocada y 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>
	`
}

¿Qué hace que esto sea bueno?

Separación clara: Cada acción hace una sola cosa
Sin condicionales: Sin lógica if (wantsCopy) del lado del servidor
Intención explícita: El nombre de la acción documenta lo que sucede
Fácil de probar: Prueba cada acción de forma independiente

Entendiendo formaction

El atributo formaction está integrado en HTML. Reemplaza el atributo action predeterminado del formulario para ese botón específico.

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

En SvelteKit, se utiliza la sintaxis ?/actionName:

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

Esto se mapea a las acciones de tu servidor:

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

¿Por qué usar formaction en lugar de JavaScript?

Mejora progresiva. El formulario funciona incluso si JavaScript falla al cargar. El navegador maneja de forma nativa el enrutamiento hacia diferentes endpoints.

Conceptos Erróneos Comunes

Abordemos algunos malentendidos sobre cuándo usar múltiples acciones:

1: Múltiples departamentos necesitan múltiples acciones

Ejemplo de lo que NO se debe hacer:

<!-- ❌ 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 qué esto es malo:

Los usuarios olvidan seleccionar un departamento
Los usuarios eligen el departamento equivocado
La estructura de tu organización no es problema del usuario

Mejor enfoque: Una sola acción con enrutamiento 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: Pruebas vs Producción = Múltiples acciones

Ejemplo de lo que NO se debe hacer:

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

Mejor enfoque: Usa la detección del entorno:

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

Marco de Decisión

Usa este diagrama de flujo para decidir qué patrón 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)

Preguntas que debes hacerte:

"¿Si eliminara esta opción, los usuarios se confundirían?"
- Si NO → Acción única
- Si SÍ → Múltiples acciones
"¿Esta elección es sobre la entrega de correos electrónicos o la lógica de la aplicación?"
- Entrega de correos → Acciones nombradas
- Lógica de la aplicación → Manejar del lado del servidor
"¿Podría un usuario elegir accidentalmente la opción incorrecta?"
- Si SÍ → Abstracción incorrecta, simplifica

Pon a Prueba tu Comprensión

Antes de continuar, intenta responder estas preguntas:

Escenario 1: Tienes un formulario de "Reportar Bug". ¿Deberían los usuarios elegir entre "Alta Prioridad" y "Baja Prioridad" usando dos botones de envío?

Clic para revelar la respuesta

No. Esto es una evaluación de severidad, no enrutamiento de correos electrónicos. Usa un único botón de envío y deja que el servidor (o el administrador) determine la prioridad según la descripción del bug. Si debes capturar la prioridad, usa un menú desplegable en el formulario, no múltiples acciones.

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, ... });
	}
};

Escenario 2: Tienes un formulario de "Enviar Factura". ¿Deberías tener botones separados para "Enviar por correo al cliente" y "Enviar por correo al cliente + Contabilidad"?

Clic para revelar la respuesta

Tal vez. Esto depende de tu proceso de negocio:

Si contabilidad SIEMPRE necesita una copia → Acción única, enviar siempre a ambos
Si contabilidad SOLO lo necesita a veces → Las acciones nombradas tienen sentido
Si no estás seguro → Comienza con una acción única (enviar siempre a ambos), puedes refactorizar después

La pregunta clave: "¿El contador necesita CADA factura, o solo algunas?"

Escenario 3: Tu formulario de suscripción envía una confirmación al usuario y una notificación a tu equipo de marketing. ¿Cuántas acciones?

Clic para revelar la respuesta

Una acción. El usuario no está eligiendo entre resultados — simplemente está suscribiéndose. El hecho de que tu equipo reciba una notificación es un detalle de implementación interno, no una elección del usuario.

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

Resumen: El Patrón Correcto para tu Situación

Usa Acción Única (Por Defecto) Cuando:

✅ El usuario quiere "enviar" o "mandar" algo
✅ Múltiples correos son TU lógica de negocio, no una elección del usuario
✅ No estás seguro de qué patrón usar (¡comienza simple!)

Ejemplo: Formularios de contacto, suscripciones a newsletters, confirmaciones de pedidos

Usa Acciones Nombradas Cuando:

✅ El usuario elige conscientemente entre diferentes resultados
✅ La elección cambia el comportamiento del correo electrónico (destinatarios, tiempo, contenido)
✅ Cada acción tiene un propósito claro y distinto

Ejemplo: "Enviar recibo" vs "Enviar recibo + copia para mí"

Evita Múltiples Acciones Cuando:

❌ El usuario está eligiendo entre TUS departamentos
❌ Estás exponiendo modos de prueba/depuración
❌ La "elección" en realidad es solo un parámetro

Solución: Maneja el enrutamiento del lado del servidor con lógica inteligente

Si te interesa aprender más sobre patrones avanzados y técnicas, puedes leer el artículo Advanced Email Templates donde exploramos cómo crear un sistema profesional de plantillas de correo electrónico.

Pruebas de Funcionalidad de Correo Electrónico

Al desarrollar funcionalidad de correo electrónico, evita usar direcciones de correo reales en entornos de desarrollo. En su lugar, confía en soluciones modernas de prueba de correo electrónico diseñadas para flujos de trabajo seguros y efectivos. En esta sección, exploraremos las herramientas más confiables para probar Nodemailer dentro de una aplicación SvelteKit.

1. Ethereal Email (Recomendado para Pruebas Rápidas)

Ethereal Email es un servicio SMTP simulado gratuito creado para probar Nodemailer. Los correos electrónicos son interceptados y visualizables en una bandeja de entrada web, sin ser entregados realmente:

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

Cómo funciona

La ventaja de Ethereal es que no necesitas registrarte ni configurar nada. Ethereal genera automáticamente una cuenta temporal cada vez que ejecutas tu aplicación en modo de desarrollo. Cuando envías un correo electrónico, Ethereal registra una URL de vista previa en la consola. Haz clic en la URL para ver el correo en la interfaz web de Ethereal.

Ejecuta tu aplicación SvelteKit en modo de desarrollo
Completa el formulario de contacto y envíalo
Revisa la terminal para ver un registro como: Preview URL: https://ethereal.email/message/...
Haz clic en la URL para ver el correo en la interfaz web de Ethereal

Cada vez que envías un correo electrónico, se registra una nueva URL de vista previa, lo que te permite ver cada correo por separado. Las cuentas expiran después de 24 horas, garantizando un entorno de pruebas limpio sin desorden.

Flujo de trabajo de pruebas:

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 flujo de trabajo es ideal para pruebas rápidas y desarrollo sin el riesgo de enviar correos electrónicos reales. Para escenarios de prueba más avanzados, puedes explorar otras herramientas como Mailpit o MailCrab, que ofrecen características adicionales como almacenamiento de mensajes, búsqueda y acceso a API.

¿Esto coincide con tu experiencia usando Ethereal? ¿O crees que los lectores necesitan más o menos detalle aquí?

Además, noto que las otras herramientas de prueba (Mailpit, MailCrab, etc.) tienen el mismo problema — muestran la instalación pero no los pasos de "¿y ahora qué?". ¿Deberíamos agregar explicaciones similares del flujo de trabajo para esas también?

2. Mailpit (Servidor SMTP Local Moderno)

Mailpit (GitHub) es un servidor SMTP local moderno, con mantenimiento activo y una hermosa interfaz web:

# Install via Homebrew (macOS)
brew install mailpit

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

# Run Mailpit
mailpit

Configurar el transporte:

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

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

Ver correos en http://localhost:8025

Características:

Interfaz moderna y responsiva
Búsqueda y filtrado
Vista previa en HTML/Texto
Visualización de archivos adjuntos
Etiquetado de mensajes
API para automatización
Multiplataforma (Windows, macOS, Linux)
Desarrollo activo (a diferencia de Mailhog)

3. MailCrab (Alternativa ligera en Rust)

MailCrab (GitHub) es una herramienta de prueba de correo súper ligera escrita en Rust:

# Install via Cargo
cargo install mailcrab

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

# Run MailCrab
mailcrab

Configurar el transporte:

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

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

Ver correos en http://localhost:1080

Características:

Muy rápido y ligero (~5MB binario)
Interfaz limpia y simple
Actualizaciones en tiempo real mediante WebSockets
Compatible con dispositivos móviles
Sin dependencias

4. smtp4dev (Multiplataforma con Docker)

smtp4dev es un servidor de prueba de correo moderno y mantenido activamente con excelente soporte para Docker. Se ejecuta como una aplicación .NET con una interfaz web y es especialmente popular entre los desarrolladores .NET, aunque funciona perfectamente para cualquier proyecto 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

Configurar el transporte:

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

Ver correos en http://localhost:3000

Características:

Interfaz moderna y elegante
Editar y reenviar correos
Soporte de retransmisión SMTP
Soporte para Docker
Multiplataforma (.NET)
Acceso a API

5. SendPigeon Local Dev Server

SendPigeon proporciona un servidor local de prueba de correo gratuito, diseñado específicamente para aplicaciones SvelteKit:

# Install SendPigeon CLI
npm install -g sendpigeon

# Start local dev server
sendpigeon dev

Configurar para pruebas:

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

Ver correos en http://localhost:3005

Características:

Construido específicamente para SvelteKit
Captura automática de correos
Vista previa visual de correos
No requiere configuración SMTP
Soporte para TypeScript
Pruebas de webhooks
Gratuito y de código abierto

Tabla comparativa

Herramienta	Puerto SMTP	Puerto Web	Instalación	Ideal para	Enlaces
Ethereal	N/A	N/A	Automática	CI/CD, pruebas rápidas	Sitio web
Mailpit	1025	8025	Brew/Binario	Desarrollo diario	Sitio web \| GitHub
MailCrab	1025	1080	Cargo/Binario	Configuración ligera	GitHub
smtp4dev	2525	3000	Docker/.NET	Flujos con Docker	GitHub
SendPigeon	N/A	3005	npm global	Proyectos SvelteKit	Sitio web

Recomendaciones

Proyectos SvelteKit: Usa SendPigeon Local Dev Server para una integración sin fricciones
Desarrollo: Usa Mailpit para pruebas locales con muchas funcionalidades
CI/CD: Usa Ethereal para pruebas automatizadas
Configuración mínima: Usa MailCrab si quieres algo ligero
Proyectos con Docker: Usa smtp4dev para flujos de trabajo en contenedores

En conclusión, todas estas herramientas resuelven el mismo problema central —pruebas seguras de correo—, pero brillan en distintos escenarios, y esa distinción importa al trabajar con Nodemailer en Svelte 5.

Usa Mailpit, MailCrab o smtp4dev cuando quieras un entorno de desarrollo local y determinista. Estas herramientas se comportan como servidores SMTP reales, te dan visibilidad completa sobre encabezados, cuerpos y archivos adjuntos, y se integran limpiamente con Nodemailer simplemente cambiando el host y el puerto. Son ideales para el desarrollo diario, depuración de plantillas y validación de casos límite sin dependencias externas. Entre ellas, Mailpit se destaca como la opción más moderna y eficiente hoy en día.

Elige Ethereal cuando quieras una solución basada en la nube sin configuración previa para experimentos rápidos, demos o ejemplos de documentación. Es excelente para aprender y prototipar, pero menos adecuada para desarrollo local de larga duración o pipelines de CI debido a su naturaleza efímera.

Recurre a SendPigeon si valoras un flujo de trabajo unificado del desarrollo a la producción. Reduce el cambio de configuración al permitir que la misma configuración del cliente funcione tanto localmente como en entornos reales, lo que puede simplificar proyectos donde el envío de correo está estrechamente acoplado a la lógica de negocio.

La conclusión clave:

- Los interceptores SMTP locales son mejores para control, realismo y reproducibilidad.
- Ethereal es mejor para pruebas rápidas y desechables.
- SendPigeon es mejor cuando minimizar la diferencia entre entornos es una prioridad.

En una configuración de Svelte 5 + Nodemailer, elige la herramienta que se ajuste a tu filosofía de desarrollo, no solo la que envía correos, sino la que mantiene tu ciclo de retroalimentación rápido, seguro y predecible.

6. Estrategia de pruebas integral

Una estrategia de pruebas robusta garantiza que la funcionalidad de correo funcione correctamente en diferentes escenarios y entornos. Esta sección cubre pruebas unitarias, pruebas de integración, estrategias de simulación y consideraciones de CI/CD.

6.1 Pruebas unitarias de acciones de formulario

Comienza probando tus acciones de formulario de forma aislada. Enfócate en la validación, el manejo de errores y la transformación de datos:

// 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 Pruebas de integración con servicios de correo

Prueba la funcionalidad real de envío de correo usando tu servidor SMTP de prueba:

// 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 Pruebas de plantillas de correo

Asegúrate de que tus plantillas de correo se rendericen correctamente y manejen casos límite:

// 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 Simulación de servicios de correo

Usa simulaciones para evitar enviar correos reales durante las pruebas:

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

Usa el simulacro en tus pruebas:

// 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 Pruebas de extremo a extremo con Playwright

Prueba el flujo completo del usuario, incluyendo el envío del formulario:

// 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 Integración con CI/CD

Configura las pruebas en tu 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 Buenas prácticas de pruebas

Qué hacer:

✅ Probar la lógica de validación de forma exhaustiva
✅ Simular servicios de correo externos en pruebas unitarias
✅ Usar servidores SMTP reales (Ethereal, Mailpit) para pruebas de integración
✅ Probar el escape de HTML para prevenir XSS
✅ Verificar que las plantillas de correo se rendericen correctamente
✅ Probar el manejo de errores y la lógica de reintentos
✅ Incluir pruebas E2E para flujos críticos del usuario

Qué no hacer:

❌ Enviar correos reales en pruebas automatizadas
❌ Codificar credenciales de prueba de forma fija
❌ Omitir las pruebas de casos límite en plantillas de correo
❌ Olvidar probar la limitación de velocidad
❌ Ignorar los escenarios de error

Objetivos de cobertura de pruebas:

Validación de formularios: 100%
Lógica de envío de correo: 90%+
Renderizado de plantillas: 90%+
Rutas críticas E2E: 100%

Manejo de errores y registro

Al enviar correos, el manejo robusto de errores es fundamental para garantizar que los problemas se detecten y se aborden de forma oportuna. Esta sección cubre las buenas prácticas para el manejo de errores, el registro y la implementación de lógica de reintentos para mejorar la confiabilidad.

Crea una función sendEmail integral con manejo de errores mejorado:

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

La lógica de reintentos es esencial para manejar fallos transitorios como inestabilidad de red, interrupciones temporales del SMTP o limitación de velocidad del proveedor. Implementar reintentos con retroceso exponencial aumenta la probabilidad de entrega exitosa, al tiempo que evita cargas innecesarias en tu aplicación o servicio de correo. Este enfoque es particularmente importante en entornos de producción, donde la confiabilidad y el manejo gracioso de fallos son 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
	);
}

Consideraciones para producción

Pasar del desarrollo a la producción requiere una consideración cuidadosa de la seguridad, la escalabilidad y la experiencia del usuario. Los sistemas de correo son especialmente vulnerables al abuso y pueden convertirse rápidamente en cuellos de botella si no se diseñan correctamente. Esta sección cubre patrones esenciales de producción que protegen tu aplicación, mantienen la reputación de entregabilidad y garantizan una entrega confiable de correos a escala.

1. Limitación de Velocidad

Por Qué Importa la Limitación de Velocidad:

Sin limitación de velocidad, tu formulario de contacto se convierte en un blanco fácil para:

Bots de spam que envían cientos de formularios por minuto
Actores maliciosos que usan tu servicio de correo para enviar spam
Abuso accidental de usuarios que hacen clic repetidamente en enviar
Agotamiento de recursos que satura tu servidor SMTP

La limitación de velocidad protege la reputación de entregabilidad de tu correo. Proveedores como Gmail rastrean los patrones de envío, y los picos repentinos en volumen pueden marcar tu dominio como fuente de spam, lo que provoca que correos legítimos sean bloqueados.

Cuándo Implementarlo:

Inmediatamente, en todos los formularios públicos
Antes de lanzar cualquier funcionalidad de contenido enviado por usuarios
Esencial para formularios de contacto, flujos de registro y restablecimiento de contraseñas

Estrategia de Implementación:

Previene el abuso con limitación de velocidad:

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

Úsalo en las acciones:

// 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 Cola para Alto Volumen

Por Qué Importan las Colas:

Enviar correos de forma sincrónica durante las solicitudes HTTP crea varios problemas críticos:

Problemas de Rendimiento:

Los usuarios esperan entre 2 y 5 segundos por las conexiones SMTP y la entrega del correo
Cada fallo en la entrega bloquea la solicitud del usuario
Los recursos del servidor quedan ocupados durante operaciones SMTP lentas
Mala experiencia de usuario con cargas de página prolongadas

Problemas de Confiabilidad:

Los tiempos de espera de red provocan que los envíos de formularios fallen
Los usuarios ven errores aunque sus datos son válidos
No hay reintentos automáticos ante fallos temporales
Los límites de velocidad de los proveedores generan fallos en cascada

Restricciones de Escalabilidad:

No se pueden enviar correos masivos sin bloquear la aplicación
Difícil implementar colas de prioridad (urgentes vs. marketing)
No hay forma de pausar/reanudar el envío de correos
Difícil escalar el envío de correos de forma independiente de los servidores web

Cuándo Implementarlo:

Necesidad inmediata (100+ correos/día): Cuando los usuarios notan envíos de formularios lentos
Planificar con anticipación (500+ correos/día): Antes de que el volumen de correos impacte la experiencia del usuario
Esencial (1000+ correos/día): Cuando la confiabilidad y la entregabilidad se vuelven críticas
Crítico (10,000+ correos/día): Cuando necesitas infraestructura de correo dedicada

Escenarios del Mundo Real:

Secuencias de correo de bienvenida con múltiples puntos de contacto
Correos de resumen diario para miles de suscriptores
Correos de restablecimiento de contraseña durante picos de tráfico
Recibos transaccionales después de una compra
Campañas de marketing con tiempos de envío precisos

Beneficios de las Colas:

Respuesta inmediata al usuario: El envío del formulario regresa de inmediato
Reintentos automáticos: Los correos fallidos se reintentan con retroceso exponencial
Limitación de velocidad: Controla la velocidad de envío para mantenerse dentro de los límites del proveedor
Manejo de prioridades: Envía correos urgentes antes que el contenido de marketing
Monitoreo: Rastrea tasas de entrega, fallos y tiempos de procesamiento
Escalabilidad: Agrega trabajadores para procesar más correos en paralelo

Implementación con BullMQ y Redis:

Para aplicaciones que envían muchos correos, usa una cola:

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

Usa la cola en las acciones:

// 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. Monitoreo de Entrega de Correos

Por Qué Importa el Monitoreo:

La entrega de correos ocurre de forma asincrónica a través de múltiples sistemas, y los fallos pueden ocurrir silenciosamente sin el monitoreo adecuado:

Escenarios de Fallo Silencioso:

El servidor SMTP acepta el correo pero nunca lo entrega (rebote suave)
El correo llega a la carpeta de spam (entregado pero no visto)
El servidor del destinatario rechaza el correo después de la aceptación inicial
La inclusión en listas negras del dominio impide la entrega a proveedores enteros
La limitación de velocidad provoca fallos temporales que se vuelven permanentes

Impacto en el Negocio:

Pérdida de ingresos: Los correos de confirmación nunca llegan, los usuarios abandonan los carritos
Carga de soporte: Los usuarios no reciben restablecimientos de contraseña, crean tickets duplicados
Daño a la reputación: Los correos transaccionales importantes van a spam
Riesgo de cumplimiento: No se puede probar que las notificaciones por correo fueron enviadas
Pesadilla de depuración: No hay forma de investigar los reportes de "nunca recibí el correo"

Qué Monitorear:

Métricas de Éxito:

Total de correos enviados por hora/día
Tiempo promedio de entrega
Tasa de éxito de entrega por dominio del destinatario
Horarios pico de envío y volúmenes

Seguimiento de Fallos:

Rebotes duros (fallos permanentes de entrega)
Rebotes suaves (fallos temporales, candidatos a reintento)
Quejas de spam y cancelaciones de suscripción
Tasas de rechazo específicas por proveedor

Salud del Sistema:

Fallos de conexión SMTP
Profundidad de la cola y tasa de procesamiento
Intentos de reintento y resultados
Errores y caídas de los trabajadores

Cuándo Implementarlo:

Desde el primer día: Registro básico (enviado/fallido con messageId)
Antes del lanzamiento: Registro en base de datos para consultas de soporte
Post-lanzamiento: Panel con tasas de entrega y alertas
A escala: Monitoreo en tiempo real con alertas sobre anomalías

Estrategia de Implementación:

Rastrea el estado de entrega de correos:

// 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. Gestión de Cancelaciones de Suscripción

Por Qué Importa la Gestión de Cancelaciones de Suscripción:

La funcionalidad de cancelación de suscripción no es solo una buena práctica—es un requisito legal en muchas jurisdicciones y es crítica para mantener la entregabilidad del correo:

Requisitos Legales:

CAN-SPAM Act (EE. UU.): Requiere un enlace visible para cancelar la suscripción en todos los correos comerciales
GDPR (UE): Los usuarios tienen derecho a retirar el consentimiento para comunicaciones de marketing
CASL (Canadá): Requiere un mecanismo claro para cancelar la suscripción
Penalizaciones: Multas de hasta $43,792 por violación (CAN-SPAM) o 4% de los ingresos (GDPR)

Impacto en la Entregabilidad:

Los usuarios que no pueden cancelar la suscripción marcan los correos como spam
Tasas altas de quejas de spam (>0.1%) activan el filtrado del proveedor
Gmail y Outlook filtran automáticamente dominios con mala experiencia de cancelación
La inclusión en listas negras puede bloquear TODOS los correos de tu dominio

Experiencia del Usuario:

Cancelación respetuosa = percepción positiva de la marca
Suscripciones forzadas = reseñas negativas y quejas en redes sociales
Cancelación con un clic = menores tasas de quejas de spam
Correos de confirmación demuestran profesionalismo

Consideraciones Técnicas:

Qué Constituye Marketing vs. Transaccional:

Marketing (requiere opción de cancelación):

Actualizaciones de boletín y blog
Anuncios y promociones de productos
Invitaciones a eventos y webinars
Destacados de funcionalidades y consejos

Transaccional (no requiere opción de cancelación):

Confirmaciones de pedidos y recibos
Correos de restablecimiento de contraseña
Alertas de seguridad de la cuenta
Notificaciones del estado del servicio

Cuando no esté claro: Opta por incluir la opción de cancelación

Requisitos de Implementación:

Enlace de cancelación en el pie de cada correo de marketing
Cancelación con un clic (sin necesidad de iniciar sesión)
Procesar cancelaciones dentro de 10 días hábiles (requisito legal)
Respetar la cancelación de inmediato (mejor práctica)
Mensaje de confirmación después de la cancelación
Opción para volver a suscribirse en caso de error

Diseño de la Base de Datos:

Almacenar la marca de tiempo de cancelación (registro de auditoría)
Tabla separada de los usuarios (privacidad/GDPR)
Índice en el correo electrónico para búsquedas rápidas
Incluir el motivo de cancelación (opcional, retroalimentación valiosa)

Mejores Prácticas:

Mostrar el enlace de cancelación de forma prominente en el pie de página
Usar lenguaje claro: "Cancelar suscripción" no "Gestionar preferencias"
No ocultar detrás de múltiples clics
Respetar preferencias granulares (resumen semanal vs. diario)
Enviar correo de confirmación (prueba de que se canceló la suscripción)

Estrategia de Implementación:

Para correos de marketing, implementa la cancelación de suscripción:

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

Verifica 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 });
}

Monitoreo Adicional:

Rastrea las métricas de cancelación para mejorar la estrategia de correo:

Tasa de cancelación por campaña
Tiempo hasta la cancelación después del registro
Motivo de cancelación (si se recopila)
Tasa de re-suscripción

Las tasas de cancelación altas (>2%) indican problemas de contenido o frecuencia que deben atenderse.

Resumen de Consideraciones para Producción:

Estos cuatro pilares—limitación de velocidad, colas, monitoreo y gestión de cancelaciones de suscripción—forman la base de un sistema de correo listo para producción. Implementa la limitación de velocidad y el monitoreo básico desde el primer día. Agrega colas antes de necesitarlas (alrededor de ~100 correos/día). Construye la funcionalidad de cancelación antes de enviar cualquier correo de marketing. Juntos, estos patrones garantizan que tu sistema de correo escale de forma confiable mientras mantiene la entregabilidad y el cumplimiento legal.

Mejores Prácticas de Seguridad

1. Nunca Expongas las Credenciales de Correo

// 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. Valida y Sanitiza la 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. Implementa CAPTCHA

Previene envíos de 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>

Verifica en el 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...
	}
}

Depuración de Problemas Comunes

Causa: Credenciales incorrectas o contraseña de aplicación no habilitada

Solución:

Habilita la verificación en dos pasos en la cuenta de Google
Genera una contraseña específica para la aplicación
Usa la contraseña de la aplicación en el archivo .env

2: Correos que van a spam

Soluciones:

Usa un dominio de remitente verificado
Agrega registros SPF, DKIM, DMARC
Evita palabras que activan filtros de spam
Incluye enlace para cancelar la suscripción
Usa un servicio SMTP de buena reputación

3: Error "ECONNREFUSED"

Causa: No se puede conectar al servidor SMTP

Solución:

// 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: El formulario no envía

Verifica:

method="POST" en el formulario
URL de la acción correcta
use:enhance de $app/forms
Consola del navegador para ver errores

Ejemplo Completo Funcional

Aquí está todo junto en una implementación lista para producción:

Estructura del Proyecto

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

Configuración del Entorno

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

Implementación Completa

Todo el código proporcionado anteriormente funciona en conjunto. Para resumir el flujo:

El usuario completa el formulario en +page.svelte
El formulario envía a la acción en +page.server.js
La acción valida con Valibot
El correo se envía a través del transporter de Nodemailer
La respuesta regresa al componente
El componente muestra mensajes de éxito/error

Conclusión

Ahora tienes una comprensión completa de cómo implementar la funcionalidad de correo en SvelteKit con Nodemailer. Puntos clave:

Seguridad del Lado del Servidor: La lógica de correo se ejecuta únicamente en el servidor
Mejora Progresiva: Los formularios funcionan sin JavaScript
Patrones Modernos: Runas de Svelte 5 y $props()
Seguridad de Tipos: TypeScript y validación con Valibot
Ligero: El pequeño tamaño de paquete de Valibot
Escalabilidad: Sistemas de cola para alto volumen
Seguridad: Limitación de velocidad, CAPTCHA, sanitización

Próximos Pasos

Implementar flujos de confirmación por correo
Agregar soporte para archivos adjuntos
Crear un sistema de notificaciones por correo
Construir suscripción a boletines
Implementar correos transaccionales

Recursos Adicionales

Para guías y tutoriales más detallados

Plantillas de Correo Avanzadas

Documentación:

Servicios de Correo:

SendPigeon - Correo transaccional moderno para desarrolladores
SendGrid - Entrega de correo basada en la nube
Mailgun - Servicio de API de correo
Amazon SES - Infraestructura de correo de AWS

Herramientas de Prueba:

Ethereal Email - Servicio SMTP falso gratuito
Mailpit - Servidor SMTP local moderno
MailCrab - Pruebas de correo en Rust ligero
smtp4dev - Servidor de pruebas de correo en .NET
SendPigeon Local Server - Pruebas de correo en SvelteKit

Pruebas de Correo:

Email on Acid - Pruebas de renderizado de correo

Esta guía se enfoca en implementaciones prácticas y listas para producción usando patrones modernos de Svelte 5 y validación con Valibot. Para más tutoriales, visita The Hackpile Chronicles.

Introducción

¿Qué es Nodemailer?

Qué Aprenderás

Prerrequisitos

Configuración del Proyecto

Configuración de Variables de Entorno

1. Crear Variables de Entorno

2. Actualizar .gitignore

3. Crear .env.example

Configurando el Transporter de Email

Entendiendo la Convención .server.js

Crear la Configuración de Email

Alternativa: Usar Otros Servicios de Email

SendGrid

Mailgun

AWS SES

SendPigeon

Opinión: Por Qué Empezar con Nodemailer en Svelte 5

Construyendo el Componente de Formulario de Contacto

Crear el Componente de Formulario

Validación

¿Por qué Valibot?

Crear el esquema de validación

Acciones del lado del servidor

Entendiendo las acciones de formulario

Crear la acción predeterminada

Conceptos clave explicados

1. La función fail

2. Métodos de FormData

3. Manejo de errores con Valibot

4. Seguridad en correos HTML

Eso es todo lo que necesitas... más o menos

Entendiendo las acciones de formulario: de lo simple a lo avanzado

Empieza aquí: el patrón de acción única

Por qué esto funciona

Cuándo necesitas múltiples acciones

Reconociendo el patrón

Construyendo comprensión: el ejemplo del recibo

El lado del servidor

Entendiendo formaction

Conceptos Erróneos Comunes

1: Múltiples departamentos necesitan múltiples acciones

2: Pruebas vs Producción = Múltiples acciones

Marco de Decisión

Pon a Prueba tu Comprensión

Resumen: El Patrón Correcto para tu Situación

Usa Acción Única (Por Defecto) Cuando:

Usa Acciones Nombradas Cuando:

Evita Múltiples Acciones Cuando:

Pruebas de Funcionalidad de Correo Electrónico

1. Ethereal Email (Recomendado para Pruebas Rápidas)

Cómo funciona

2. Mailpit (Servidor SMTP Local Moderno)

3. MailCrab (Alternativa ligera en Rust)

4. smtp4dev (Multiplataforma con Docker)

5. SendPigeon Local Dev Server

Tabla comparativa

Recomendaciones

6. Estrategia de pruebas integral

6.1 Pruebas unitarias de acciones de formulario

6.2 Pruebas de integración con servicios de correo

6.3 Pruebas de plantillas de correo

6.4 Simulación de servicios de correo

6.5 Pruebas de extremo a extremo con Playwright

6.6 Integración con CI/CD

6.7 Buenas prácticas de pruebas

Manejo de errores y registro

Implementar lógica de reintentos

Consideraciones para producción

1. Limitación de Velocidad

2. Sistema de Cola para Alto Volumen

3. Monitoreo de Entrega de Correos

4. Gestión de Cancelaciones de Suscripción

Mejores Prácticas de Seguridad

1. Nunca Expongas las Credenciales de Correo

2. Valida y Sanitiza la Entrada

3. Implementa CAPTCHA

Depuración de Problemas Comunes

1: "Invalid login: 535 Authentication failed"

2: Correos que van a spam

1. La función `fail`

2. Métodos de `FormData`