EmDash utiliza correo electrónico para inicio de sesión con enlace mágico, invitaciones de usuario y recuperación de cuenta. Un proveedor entrega el correo: el transporte SMTP integrado en EmDash o un plugin de proveedor.
Esta guía cubre cómo funciona el flujo de correo electrónico, qué obtiene out of the box en desarrollo y cómo conectar un proveedor real para producción.
Cómo funciona la entrega de correo electrónico
Un único proveedor activo entrega todo el correo saliente. Si no hay ningún proveedor activo, las funciones que necesitan correo electrónico no están disponibles y los enlaces de invitación deben copiarse y compartirse manualmente desde la página de Usuarios.
Puede ver el estado actual en Settings → Email en el administrador: si un proveedor está activo, qué proveedor es, y un botón send test email que ejercita todo el flujo.
Desarrollo: Proveedor de consola integrado
En desarrollo (astro dev), EmDash activa automáticamente un proveedor de consola integrado cuando no hay ningún otro proveedor activo. No envía nada — registra cada correo electrónico en la terminal y mantiene los últimos 100 mensajes en memoria.
Esto significa que los enlaces mágicos e invitaciones funcionan out of the box en desarrollo: solicite un enlace mágico, luego copie la URL de su salida de terminal. También puede listar correos electrónicos capturados en el endpoint solo de desarrollo GET /_emdash/api/dev/emails (y eliminarlos con DELETE).
Si Settings → Email sigue mostrando la consola después de agregar un plugin de proveedor o configurar SMTP, seleccione ese proveedor allí y guarde.
El proveedor de consola es solo para desarrollo y nunca se ejecuta en compilaciones de producción.
Producción: Transporte SMTP integrado
Si tiene credenciales SMTP (por ejemplo de Brevo, Office 365, Fastmail, Amazon SES o su propio servidor de correo), EmDash puede enviar a través de ellas sin un plugin. El transporte exige TLS antes de autenticarse, admite AUTH PLAIN y AUTH LOGIN, y rechaza el puerto 25.
Puede configurarlo de dos maneras:
- En el admin: abra Settings → Email, elija SMTP, complete los datos del servidor y guarde. Al guardar, los ajustes se almacenan en la base de datos y se selecciona SMTP. EmDash cifra la contraseña con
EMDASH_ENCRYPTION_KEY, por lo que esa clave debe estar definida. Los ajustes guardados en el admin tienen prioridad sobre las variables de entorno, así que cambie la contraseña en el admin cuando la rote. - Con variables de entorno: defina las siguientes variables en el entorno de proceso del servidor. En Cloudflare, use
wrangler secret put, y.envpara el desarrollo local. En Node, niastro devni el servidor compilado cargan.env, así que exporte las variables o inicie el servidor connode --env-file=.env. Consulte Secrets & Key Management.
| Variable | Ejemplo | Notas |
|---|---|---|
EMAIL_SMTP_HOST | smtp.example.com | Obligatoria |
EMAIL_SMTP_PORT | 587 | Opcional; por defecto 587. Use 465 para TLS implícito |
EMAIL_SMTP_USER | [email protected] | Obligatoria; el inicio de sesión SMTP |
EMAIL_SMTP_PASS | your-smtp-password | Obligatoria; guárdela como secreto |
EMAIL_SMTP_SECURE | tls o starttls | Opcional; el puerto 465 usa tls, cualquier otro puerto usa starttls |
EMAIL_SMTP_FROM | My Site <[email protected]> | Remitente predeterminado opcional |
EMAIL_SMTP_FROM_NAME | My Site | Nombre para mostrar opcional de EMAIL_SMTP_FROM_EMAIL |
EMAIL_SMTP_FROM_EMAIL | [email protected] | Dirección de remitente opcional; tiene prioridad sobre EMAIL_SMTP_FROM |
EMAIL_SMTP_REPLY_TO | [email protected] | Dirección Reply-To opcional |
Sin una variable de remitente, EmDash envía desde EMAIL_SMTP_USER. Si su inicio de sesión SMTP no es una dirección de correo electrónico, defina EMAIL_SMTP_FROM_EMAIL o EMAIL_SMTP_FROM; de lo contrario, la entrega falla con Invalid sender address for SMTP delivery. En ese caso, Settings → Email pide un correo de remitente antes de guardar.
Cuando las variables de entorno están completas, EmDash envía mediante SMTP a menos que haya un plugin de proveedor de correo activo o que se haya seleccionado otro proveedor en Settings → Email. Para seguir usando SMTP junto con un plugin de proveedor, seleccione allí SMTP y guarde.
En Cloudflare Workers, el transporte necesita el flag de compatibilidad nodejs_compat. Consulte la guía de despliegue en Cloudflare.
Producción: Instalar un plugin de proveedor
Cloudflare Workers
En Cloudflare, use el plugin cloudflareEmail() de @emdash-cms/cloudflare/plugins. Envía a través de Cloudflare Email Sending sobre un binding send_email del Worker, por lo que no necesita cuenta externa ni clave API. La guía de despliegue de Cloudflare le guía a través de la incorporación del dominio remitente, la adición del binding y el registro del plugin.
Node y otras plataformas
La familia de plugins mantenida por la comunidad emdash-smtp cubre SMTP genérico más proveedores alojados, incluyendo Amazon SES, Brevo, Mailgun, Postmark, Resend, SendGrid, Zoho y más.
pnpm add emdash-smtp
La siguiente configuración registra el plugin con EmDash:
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { emdashSmtp } from "emdash-smtp";
export default defineConfig({
integrations: [
emdash({
// ...su configuración de base de datos/almacenamiento
plugins: [emdashSmtp()],
}),
],
});
Las credenciales del proveedor se configuran a través de la configuración propia del plugin — consulte su README para la matriz de proveedores y detalles de configuración.
Dónde residen las credenciales del proveedor
Los plugins de proveedor declaran sus claves API y contraseñas como configuraciones de plugin. Ingréselas en la página de configuración del plugin en el administrador; EmDash las almacena en la base de datos junto con otras configuraciones de plugin, y rotar una clave significa pegar el nuevo valor allí. Secrets & Key Management describe el almacenamiento y sus advertencias.
Si un plugin puede leer un secreto de despliegue (wrangler secret put, .env) depende de su formato, así que siga su README. Los plugins en sandbox no pueden acceder a process.env o bindings de plataforma. Un plugin nativo puede leer process.env; no debe usar import.meta.env, que se inserta en tiempo de compilación y hornea el valor de la máquina de compilación en el bundle.
Seleccionar un proveedor y probar
-
Instale y active el plugin de proveedor, luego abra Settings → Email en el administrador.
-
Si hay más de un plugin de proveedor instalado, elija el activo allí — solo uno entrega a la vez.
-
Use Send test email para verificar el flujo completo de extremo a extremo. El resultado muestra errores de entrega directamente, que es la forma más rápida de depurar credenciales.
Resolución de problemas
- “No email provider is configured”: no hay ningún proveedor activo. Configure SMTP o active un plugin de proveedor, luego selecciónelo en Settings → Email.
- Magic links / invitaciones silenciosamente no disponibles — misma causa. Sin un proveedor, la página de Usuarios aún crea invitaciones, pero debe copiar el enlace de invitación manualmente.
- Funciona en desarrollo, falla en producción — el desarrollo usa el proveedor de consola integrado, que enmascara un proveedor de producción faltante. Verifique Settings → Email en el sitio desplegado.
- Los correos electrónicos llegan al spam — configure SPF/DKIM/DMARC para su dominio remitente en su proveedor de correo electrónico; esto es del lado del proveedor, no una configuración de EmDash.
Relacionado
- Autenticación — enlaces mágicos, invitaciones y flujos de recuperación que dependen del correo electrónico
- Referencia de hooks de correo electrónico —
email:beforeSend,email:deliver,email:afterSend