¿Qué hace Integración de correo electrónico con Mailtrap?
Patrones para agregar envío de correos electrónicos transaccionales a una aplicación utilizando la API de correo electrónico y 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 electrónico" (confirmación de registro, restablecimiento de contraseña, notificaciones, recibos)
- Depurar por qué los correos electrónicos no llegan en desarrollo/pruebas
- Configurar la primera integración de envío de correo electrónico de un proyecto
- Revisar código que llama directamente a una API de correo electrónico sin separación de Sandbox
Conceptos fundamentales
Separación de Sandbox y Producción. Mailtrap proporciona una API de Sandbox que captura correos electrónicos 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 utiliza un endpoint separado con dominio verificado. Nunca apuntes un entorno de desarrollo al endpoint de envío de producción.
Autenticación. Las solicitudes utilizan un token Bearer en el encabezado Authorization. Los tokens tienen alcance por proyecto; normalmente, sandbox y producción usan 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 silenciosos de entrega o que los correos terminen en la carpeta de spam.
Ejemplos de código
// Envío mediante 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: "Your App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Email send failed: ${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}`;
Anti-patrones
| Anti-patrón | Por qué es un problema | En su lugar |
|---|---|---|
| Usar el endpoint de envío de producción en desarrollo/pruebas | Los correos de prueba reales llegan a bandejas de entrada reales, con riesgo de quejas de spam y fuga de datos de prueba | Enrutar los entornos que no son de producción al endpoint de Sandbox |
| Codificar tokens de API en el código fuente | Riesgo de fuga de credenciales si se confirma en el control de versiones | Cargar tokens desde variables de entorno / administrador de secretos |
| Enviar antes de completar la verificación del dominio | Los correos electrónicos fallan silenciosamente o terminan en spam | Verificar los registros SPF/DKIM/DMARC antes de habilitar el envío en producción |
| Sin reintentos ni manejo de errores en fallos de envío | Fallos silenciosos de notificación (por ejemplo, el usuario nunca recibe el correo de restablecimiento de contraseña) | Verificar el estado de la respuesta, registrar los fallos y mostrar errores procesables |
Mejores prácticas
- Mantener los tokens de sandbox y producción en variables de entorno separadas; nunca compartir un token entre entornos
- Verificar los registros DNS del dominio de envío antes de cualquier lanzamiento en producción que involucre correo electrónico
- Registrar los fallos de entrega con suficiente contexto para depurar (destinatario, plantilla, marca de tiempo, código de respuesta)
- Tratar el envío de correo electrónico como una llamada de red falible: envolver en try/catch, nunca asumir éxito
Habilidades relacionadas
api-and-interface-design, security-and-hardening, ci-cd-and-automation