¿Qué hace Integración de Correo Electrónico con Mailtrap?
Patrones para añadir envío de correos electrónicos transaccionales a una aplicación utilizando la API de Correo Electrónico y el Sandbox de Mailtrap, cubriendo autenticación, separación de entornos y errores comunes de entrega.
Cuándo Activar
- Implementar una función de "enviar correo" (confirmación de registro, restablecimiento de contraseña, notificaciones, recibos)
- Depurar por qué los correos no llegan en desarrollo/pruebas
- Configurar la primera integración de envío de correo de un proyecto
- Revisar código que llama directamente a una API de correo sin separación de sandbox
Conceptos Clave
Separación Sandbox vs. Producción. Mailtrap proporciona una API Sandbox que captura los correos sin entregarlos, utilizada en desarrollo/pruebas para que los correos de prueba nunca lleguen a bandejas de entrada reales. El envío en producción usa un endpoint separado con dominio verificado. Nunca apuntes un entorno de desarrollo al endpoint de envío de producción.
Autenticación. Las solicitudes usan un token Bearer en la cabecera Authorization. Los tokens tienen alcance por proyecto; sandbox y producción suelen usar tokens diferentes.
Verificación de dominio. El envío en producción requiere verificar un dominio de envío mediante registros DNS (SPF, DKIM, DMARC) antes de que Mailtrap entregue a destinatarios reales. Omitir esto provoca fallos de entrega silenciosos o el envío a la carpeta de spam.
Ejemplos de Código
// Envío a través de la API de Correo Electrónico de Mailtrap (producción)
async function sendEmail(to: string, subject: string, html: string) {
const response = await fetch("https://send.api.mailtrap.io/api/send", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.MAILTRAP_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: { email: "[email protected]", name: "Tu App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Envío de correo falló: ${response.status}`);
}
return response.json();
}
// Misma llamada, enrutada al Sandbox en entornos que no son producción
const MAILTRAP_ENDPOINT = process.env.NODE_ENV === "production"
? "https://send.api.mailtrap.io/api/send"
: `https://sandbox.api.mailtrap.io/api/send/${process.env.MAILTRAP_INBOX_ID}`;
Antipatrones
| Antipatrón | Por qué es un Problema | En su lugar |
|---|---|---|
| Usar el endpoint de producción en desarrollo/pruebas | Los correos de prueba llegan a bandejas reales, arriesgando quejas de spam y filtración de datos de prueba | Enrutar entornos que no sean de producción al endpoint Sandbox |
| Hardcodear tokens API en el código fuente | Riesgo de filtración de credenciales si se sube al control de versiones | Cargar tokens desde variables de entorno / gestor de secretos |
| Enviar antes de completar la verificación de dominio | Los correos fallan silenciosamente o caen en spam | Verificar registros SPF/DKIM/DMARC antes de habilitar el envío en producción |
| Sin reintento/manejo de errores en fallos de envío | Fallos silenciosos de notificación (ej: el usuario nunca recibe el correo de restablecimiento de contraseña) | Verificar el estado de la respuesta, registrar fallos, mostrar errores accionables |
Mejores Prácticas
- Mantén los tokens de sandbox y producción en variables de entorno separadas; nunca compartas un token entre entornos
- Verifica los registros DNS del dominio de envío antes de cualquier lanzamiento a producción que involucre correo
- Registra los fallos de entrega con suficiente contexto para depurar (destinatario, plantilla, marca de tiempo, código de respuesta)
- Trata el envío de correo como una llamada de red falible: envuélvelo en try/catch, nunca asumas éxito
Habilidades Relacionadas
api-and-interface-design, security-and-hardening, ci-cd-and-automation