pagetop/extensions/pagetop-mail/README.md
Manuel Cillero ce9635f9a8 ✨ (mail): Añade la extensión pagetop-mail
Envío de correo con lettre: plantillas con diseño y versión en texto,
adjuntos, transporte configurable y vista previa de mensajes.
2026-10-19 01:06:20 +02:00

8.3 KiB

PageTop Mail

Envío de correo electrónico para aplicaciones PageTop.

Doc API Crates.io Descargas Licencia

Envía correos en texto plano y HTML, con archivos adjuntos e imágenes incrustadas, por SMTP, con el programa sendmail o a archivos .eml, todo configurado en los archivos TOML de la aplicación. Los correos pueden crearse con plantillas que traducen sus textos al idioma del destinatario, y comparten un diseño HTML común que la aplicación puede cambiar. Para las pruebas, los correos pueden guardarse en memoria en lugar de enviarse.

Sobre PageTop

PageTop es un entorno de desarrollo que reivindica la esencia de la web clásica para crear soluciones web SSR (renderizadas en el servidor) modulares, extensibles y configurables, basadas en HTML, CSS y JavaScript.

Guía rápida

Añade la dependencia a tu Cargo.toml:

[dependencies]
pagetop-mail = "..."

Declara la extensión en tu aplicación o en la extensión que envíe correos:

use pagetop::prelude::*;

struct MyApp;

#[async_trait]
impl Extension for MyApp {
    fn dependencies(&self) -> Vec<ExtensionRef> {
        vec![&pagetop_mail::Mail]
    }
}

Configura el envío en la sección [mail] (todas las opciones en el módulo config):

[mail]
transport = "smtp"
from      = "Mi Aplicación <no-reply@example.com>"
base_url  = "https://example.com"

[mail.smtp]
host     = "smtp.example.com"
security = "starttls"           # "none", "opportunistic", "starttls" o "tls".
username = "no-reply@example.com"
password = "secreto"            # Mejor en config/local.toml, que no se versiona.

Sin configurar, los correos se escriben en las trazas en lugar de enviarse (transport = "log"), así que una aplicación en desarrollo nunca envía correo real por error. La configuración se valida al arrancar: un ajuste no válido detiene la aplicación con un mensaje que indica el problema.

Envía un correo con Email:

use pagetop::prelude::*;
use pagetop_mail::prelude::*;

async fn notify() -> Result<(), MailError> {
    Email::new()
        .with_to("Ana Pérez <ana@example.com>")
        .with_subject("Tu pedido ha salido")
        .with_text("Tu pedido 1234 ha salido hoy.")
        .with_html(html! {
            p { "Tu pedido " strong { "1234" } " ha salido hoy." }
        })
        .send()
        .await
}

Email::send() espera a que el correo se entregue; Email::send_later() lo envía en segundo plano y registra en las trazas los errores.

Plantillas

Una MailTemplate genera el asunto, el HTML y el texto de un correo a partir de sus datos, con los textos traducidos mediante Lc al idioma del contexto que recibe. Así, cada extensión define sus correos como tipos propios, y el mismo correo se envía a cada destinatario en su idioma:

use pagetop::prelude::*;
use pagetop_mail::prelude::*;

include_locales!(LOCALES_SHOP);

struct Welcome {
    name: String,
}

impl MailTemplate for Welcome {
    fn subject(&self, cx: &Context) -> String {
        Lc::t("welcome-subject", &LOCALES_SHOP).lookup(cx).unwrap_or_default()
    }

    fn html(&self, cx: &Context) -> Option<Markup> {
        let greeting = Lc::t("welcome-greeting", &LOCALES_SHOP).with_arg("name", self.name.clone());
        Some(html! {
            p { (greeting.using(cx)) }
            p {
                a href=(absolute_url("/shop")) { (Lc::t("welcome-visit", &LOCALES_SHOP).using(cx)) }
            }
        })
    }
}

async fn welcome(request: HttpRequest) -> Result<(), MailError> {
    // El contexto de la petición: el correo sale en el idioma de quien se acaba de registrar.
    let cx = Context::new(request);
    Email::from_template(&Welcome { name: "Ana".to_string() }, &cx)
        .with_to("ana@example.com")
        .send()
        .await
}

Enlaces en los correos

Los enlaces de un correo deben ser absolutos. absolute_url() antepone a una ruta la URL pública de la aplicación, que se configura en mail.base_url. No se deduce de la petición, porque la cabecera Host la elige el cliente y un atacante podría hacer que los enlaces de un correo de recuperación de contraseña apuntaran a su propio servidor.

Adjuntos e imágenes incrustadas

Un Attachment se crea con un contenido en memoria o leyendo un archivo, y su tipo MIME se deduce del nombre. Con Attachment::with_content_id() se incrusta en el HTML, que lo muestra con cid::

use pagetop::prelude::*;
use pagetop_mail::prelude::*;

async fn report(png: Vec<u8>) -> Result<(), MailError> {
    Email::new()
        .with_to("ana@example.com")
        .with_subject("Informe")
        .with_html(html! { img src="cid:logo" alt="Logo"; p { "Adjunto el informe." } })
        .with_attachment(Attachment::new("logo.png", png).with_content_id("logo"))
        .with_attachment(Attachment::from_path("informes/octubre.pdf").await?)
        .send()
        .await
}

Diseño común del HTML

El HTML de los correos es sólo su contenido: al enviarlos se envuelve en un documento con un diseño sobrio y neutro. La aplicación puede darle su propia imagen a todos los correos, incluidos los de otras extensiones, registrando la acción RenderMailLayout.

Vistas previas en el navegador

Con previews = true en [mail] (sólo en desarrollo), /mail/preview lista los correos que las extensiones declaran con la acción DeclareMailPreviews, y muestra cada uno con datos de ejemplo: cabeceras, HTML con el diseño común, texto plano y adjuntos, sin enviar nada.

Texto plano automático

Si un correo sólo tiene HTML, al enviarlo se genera su texto plano a partir del contenido: bloques separados por líneas, listas con guiones, y la dirección de cada enlace entre paréntesis.

Transportes

Se elige en mail.transport:

Valor Uso
"smtp" Producción. Servidor SMTP con conexiones reutilizables y cifrado TLS.
"sendmail" Producción, con un servidor de correo local (Postfix, Exim...).
"file" Desarrollo. Guarda cada correo como .eml para abrirlo con un cliente.
"log" Por defecto. Escribe los correos en las trazas, sin enviarlos.
"memory" Pruebas. Guarda los correos en memoria para comprobarlos con outbox.

En entornos de pruebas con datos reales, mail.redirect_to entrega todos los correos a una sola dirección, sin cambiar sus cabeceras.

Para probar el envío SMTP en desarrollo sin enviar correo real, un servidor como Mailpit recoge los correos y los muestra en el navegador:

[mail]
transport = "smtp"

[mail.smtp]
host     = "localhost"
port     = 1025
security = "none"

Créditos

Este crate se apoya en lettre, la biblioteca de correo de referencia en Rust, distribuida bajo licencia MIT.

Advertencia

PageTop es un proyecto personal para aprender Rust y conocer su ecosistema. Su API está sujeta a cambios frecuentes. No se recomienda su uso en producción, al menos hasta que se libere la versión 1.0.0.

Licencia

El código está disponible bajo una doble licencia:

Puedes elegir la licencia que prefieras. Este enfoque de doble licencia es el estándar de facto en el ecosistema Rust.