✨ (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.
This commit is contained in:
parent
b3a7d40930
commit
ce9635f9a8
25 changed files with 3508 additions and 0 deletions
345
extensions/pagetop-mail/src/email.rs
Normal file
345
extensions/pagetop-mail/src/email.rs
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
//! Correos electrónicos ([`Email`]).
|
||||
|
||||
use pagetop::prelude::*;
|
||||
|
||||
use crate::{Attachment, MailError, MailTemplate, Mailbox, layout, text, transport};
|
||||
|
||||
use lettre::Message;
|
||||
use lettre::message::{MultiPart, MultiPartBuilder, SinglePart};
|
||||
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::time::{SystemTime, UNIX_EPOCH};
|
||||
|
||||
/// Correo electrónico listo para enviar.
|
||||
///
|
||||
/// Se compone con los métodos `with_*()` y se envía con [`send()`](Self::send), que espera a que
|
||||
/// el servidor lo acepte, o con [`send_later()`](Self::send_later), que lo envía en segundo plano.
|
||||
/// También puede crearse a partir de una plantilla con [`from_template()`](Self::from_template).
|
||||
///
|
||||
/// Un correo puede tener texto plano, HTML o ambos (los clientes de correo muestran el que
|
||||
/// prefieran), además de archivos adjuntos y de imágenes incrustadas en el HTML (ver
|
||||
/// [`Attachment`]). El HTML de [`with_html()`](Self::with_html) es sólo el contenido: al enviarlo
|
||||
/// se envuelve en el diseño común de los correos (ver
|
||||
/// [`RenderMailLayout`](crate::RenderMailLayout)).
|
||||
///
|
||||
/// Si sólo tiene HTML, al enviarlo se genera el texto plano a partir de él, porque los filtros de
|
||||
/// correo no deseado penalizan los correos sin texto. Escríbelo con
|
||||
/// [`with_text()`](Self::with_text) sólo si el generado no queda bien.
|
||||
///
|
||||
/// Si no se indica el remitente o la dirección de respuesta se usan los de la configuración
|
||||
/// (`mail.from` y `mail.reply_to`). Las direcciones se validan al enviar.
|
||||
///
|
||||
/// # Ejemplo
|
||||
///
|
||||
/// ```rust,no_run
|
||||
/// use pagetop::prelude::*;
|
||||
/// use pagetop_mail::prelude::*;
|
||||
///
|
||||
/// async fn send_report(pdf: Vec<u8>) -> Result<(), MailError> {
|
||||
/// Email::new()
|
||||
/// .with_to("Ana Pérez <ana@example.com>")
|
||||
/// .with_cc("contabilidad@example.com")
|
||||
/// .with_subject("Informe mensual")
|
||||
/// .with_text("Adjunto el informe del mes.")
|
||||
/// .with_html(html! {
|
||||
/// p { "Adjunto el " strong { "informe" } " del mes." }
|
||||
/// })
|
||||
/// .with_attachment(Attachment::new("informe.pdf", pdf))
|
||||
/// .send()
|
||||
/// .await
|
||||
/// }
|
||||
/// ```
|
||||
#[derive(AutoDefault, Clone, Debug, Getters)]
|
||||
pub struct Email {
|
||||
/// Remitente, si se ha indicado.
|
||||
from: Option<Mailbox>,
|
||||
/// Dirección de respuesta, si se ha indicado.
|
||||
reply_to: Option<Mailbox>,
|
||||
/// Destinatarios principales.
|
||||
to: Vec<Mailbox>,
|
||||
/// Destinatarios en copia.
|
||||
cc: Vec<Mailbox>,
|
||||
/// Destinatarios en copia oculta.
|
||||
bcc: Vec<Mailbox>,
|
||||
/// Asunto.
|
||||
subject: String,
|
||||
/// Texto plano, si lo tiene.
|
||||
text: Option<String>,
|
||||
/// HTML, si lo tiene: el contenido mientras se compone y el documento completo una vez
|
||||
/// enviado.
|
||||
html: Option<Markup>,
|
||||
#[getters(skip)]
|
||||
html_is_document: bool,
|
||||
/// Archivos adjuntos e imágenes incrustadas.
|
||||
attachments: Vec<Attachment>,
|
||||
#[getters(skip)]
|
||||
langid: Option<&'static LanguageIdentifier>,
|
||||
}
|
||||
|
||||
impl Email {
|
||||
/// Crea un correo vacío.
|
||||
pub fn new() -> Self {
|
||||
Email::default()
|
||||
}
|
||||
|
||||
/// Crea un correo con el asunto, el HTML y el texto de una plantilla, generados en el idioma
|
||||
/// del contexto, que también es el del diseño común del HTML.
|
||||
///
|
||||
/// El contexto puede ser el de la petición en curso, si el destinatario es quien la hace (p.
|
||||
/// ej. al registrarse), o uno creado para el destinatario con
|
||||
/// `Context::default().with_langid(...)`.
|
||||
pub fn from_template(template: &impl MailTemplate, cx: &Context) -> Self {
|
||||
let mut email = Email::new()
|
||||
.with_subject(template.subject(cx))
|
||||
.with_langid(cx);
|
||||
if let Some(html) = template.html(cx) {
|
||||
email.alter_html(html);
|
||||
}
|
||||
if let Some(text) = template.text(cx) {
|
||||
email.alter_text(text);
|
||||
}
|
||||
email
|
||||
}
|
||||
|
||||
/// Idioma del correo: el indicado con [`with_langid()`](Self::with_langid) o, si no, el idioma
|
||||
/// por defecto de la aplicación.
|
||||
pub fn langid(&self) -> &'static LanguageIdentifier {
|
||||
self.langid.unwrap_or_else(Locale::default_langid)
|
||||
}
|
||||
|
||||
/// Envía el correo y espera a que se entregue (al servidor SMTP, a *sendmail*, al archivo...).
|
||||
///
|
||||
/// Falla si alguna dirección o el tipo MIME de algún adjunto no son válidos, si falta el
|
||||
/// remitente o los destinatarios, o si la entrega falla.
|
||||
pub async fn send(self) -> Result<(), MailError> {
|
||||
transport::deliver(self).await
|
||||
}
|
||||
|
||||
/// Envía el correo en segundo plano, sin esperar al resultado. Si falla, se registra el error
|
||||
/// en las trazas.
|
||||
///
|
||||
/// La respuesta de la petición no espera al servidor de correo, y su tiempo no revela si el
|
||||
/// correo se ha enviado (p. ej., si existe la cuenta para la que se pide recuperar la
|
||||
/// contraseña). A cambio, los correos pendientes se pierden si la aplicación se detiene antes
|
||||
/// de enviarlos, y no se reintentan si fallan.
|
||||
pub fn send_later(self) {
|
||||
tokio::spawn(async move {
|
||||
let subject = self.subject.clone();
|
||||
if let Err(err) = self.send().await {
|
||||
let mut message = err.to_string();
|
||||
let mut source = std::error::Error::source(&err);
|
||||
while let Some(cause) = source {
|
||||
message.push_str(": ");
|
||||
message.push_str(&cause.to_string());
|
||||
source = cause.source();
|
||||
}
|
||||
trace::error!("Cannot send email \"{subject}\": {message}");
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// Completa el correo antes de enviarlo: remitente y dirección de respuesta por defecto, el
|
||||
// texto plano a partir del HTML si no tiene, y el documento HTML con el diseño común. El texto
|
||||
// se genera antes del diseño para que no incluya su pie.
|
||||
pub(crate) fn prepare(mut self, from: Option<&Mailbox>, reply_to: Option<&Mailbox>) -> Self {
|
||||
if self.from.is_none() {
|
||||
self.from = from.cloned();
|
||||
}
|
||||
if self.reply_to.is_none() {
|
||||
self.reply_to = reply_to.cloned();
|
||||
}
|
||||
if self.text.is_none()
|
||||
&& let Some(html) = &self.html
|
||||
{
|
||||
self.text = Some(text::html_to_text(html.as_str()));
|
||||
}
|
||||
if !self.html_is_document
|
||||
&& let Some(content) = self.html.take()
|
||||
{
|
||||
let cx = Context::default().with_langid(&Locale::Resolved(self.langid()));
|
||||
self.html = Some(layout::render(&cx, &self, &content));
|
||||
self.html_is_document = true;
|
||||
}
|
||||
self
|
||||
}
|
||||
|
||||
// Compone el mensaje MIME:
|
||||
//
|
||||
// - texto y HTML -> multipart/alternative (el texto primero, el preferido al final).
|
||||
// - HTML con imágenes incrustadas -> multipart/related con el HTML y las imágenes.
|
||||
// - con adjuntos -> multipart/mixed con el cuerpo y los adjuntos.
|
||||
pub(crate) fn to_message(&self) -> Result<Message, MailError> {
|
||||
let from = self.from.as_ref().ok_or(MailError::MissingFrom)?;
|
||||
if self.to.is_empty() && self.cc.is_empty() && self.bcc.is_empty() {
|
||||
return Err(MailError::NoRecipients);
|
||||
}
|
||||
|
||||
let from = from.to_lettre()?;
|
||||
let mut builder = Message::builder()
|
||||
.message_id(Some(message_id(from.email.domain())))
|
||||
.from(from)
|
||||
.subject(self.subject.as_str());
|
||||
if let Some(reply_to) = &self.reply_to {
|
||||
builder = builder.reply_to(reply_to.to_lettre()?);
|
||||
}
|
||||
for mailbox in &self.to {
|
||||
builder = builder.to(mailbox.to_lettre()?);
|
||||
}
|
||||
for mailbox in &self.cc {
|
||||
builder = builder.cc(mailbox.to_lettre()?);
|
||||
}
|
||||
for mailbox in &self.bcc {
|
||||
builder = builder.bcc(mailbox.to_lettre()?);
|
||||
}
|
||||
|
||||
let has_html = self.html.is_some();
|
||||
let html = match &self.html {
|
||||
Some(html) => {
|
||||
let part = SinglePart::html(html.as_str().to_owned());
|
||||
let mut inline = self.attachments.iter().filter(|a| a.is_inline()).peekable();
|
||||
if inline.peek().is_some() {
|
||||
let images = inline
|
||||
.map(|attachment| attachment.to_part(true).map(Part::Single))
|
||||
.collect::<Result<Vec<_>, _>>()?;
|
||||
Some(multipart(MultiPart::related(), Part::Single(part), images))
|
||||
} else {
|
||||
Some(Part::Single(part))
|
||||
}
|
||||
}
|
||||
None => None,
|
||||
};
|
||||
let text = self
|
||||
.text
|
||||
.as_ref()
|
||||
.map(|t| Part::Single(SinglePart::plain(t.clone())));
|
||||
let mut body = match (text, html) {
|
||||
(Some(text), Some(html)) => multipart(MultiPart::alternative(), text, vec![html]),
|
||||
(Some(part), None) | (None, Some(part)) => part,
|
||||
(None, None) => Part::Single(SinglePart::plain(String::new())),
|
||||
};
|
||||
|
||||
let attached = self
|
||||
.attachments
|
||||
.iter()
|
||||
.filter(|a| !(has_html && a.is_inline()))
|
||||
.map(|attachment| attachment.to_part(false).map(Part::Single))
|
||||
.collect::<Result<Vec<_>, _>>()?;
|
||||
if !attached.is_empty() {
|
||||
body = multipart(MultiPart::mixed(), body, attached);
|
||||
}
|
||||
|
||||
match body {
|
||||
Part::Single(part) => builder.singlepart(part),
|
||||
Part::Multi(multi) => builder.multipart(multi),
|
||||
}
|
||||
.map_err(MailError::Build)
|
||||
}
|
||||
}
|
||||
|
||||
#[builder_impl]
|
||||
impl Email {
|
||||
// **< Email BUILDER >**************************************************************************
|
||||
|
||||
/// Establece el remitente, en lugar del de la configuración (`mail.from`).
|
||||
pub fn with_from(mut self, from: impl Into<Mailbox>) -> Self {
|
||||
self.from = Some(from.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece la dirección de respuesta, en lugar de la de la configuración (`mail.reply_to`).
|
||||
pub fn with_reply_to(mut self, reply_to: impl Into<Mailbox>) -> Self {
|
||||
self.reply_to = Some(reply_to.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un destinatario principal (`To`).
|
||||
pub fn with_to(mut self, to: impl Into<Mailbox>) -> Self {
|
||||
self.to.push(to.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un destinatario en copia (`Cc`).
|
||||
pub fn with_cc(mut self, cc: impl Into<Mailbox>) -> Self {
|
||||
self.cc.push(cc.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un destinatario en copia oculta (`Bcc`), que no ven los demás destinatarios.
|
||||
pub fn with_bcc(mut self, bcc: impl Into<Mailbox>) -> Self {
|
||||
self.bcc.push(bcc.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el asunto.
|
||||
pub fn with_subject(mut self, subject: impl Into<String>) -> Self {
|
||||
self.subject = subject.into();
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el texto plano.
|
||||
pub fn with_text(mut self, text: impl Into<String>) -> Self {
|
||||
self.text = Some(text.into());
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el contenido HTML, que al enviarse se envuelve en el diseño común de los correos.
|
||||
pub fn with_html(mut self, content: Markup) -> Self {
|
||||
self.html = Some(content);
|
||||
self.html_is_document = false;
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el documento HTML completo, que se envía tal cual, sin el diseño común. Útil si el
|
||||
/// HTML se genera con otra herramienta.
|
||||
pub fn with_html_document(mut self, document: Markup) -> Self {
|
||||
self.html = Some(document);
|
||||
self.html_is_document = true;
|
||||
self
|
||||
}
|
||||
|
||||
/// Añade un archivo adjunto o una imagen incrustada.
|
||||
pub fn with_attachment(mut self, attachment: Attachment) -> Self {
|
||||
self.attachments.push(attachment);
|
||||
self
|
||||
}
|
||||
|
||||
/// Establece el idioma del correo, que usa el diseño común del HTML.
|
||||
pub fn with_langid(mut self, language: &impl LangId) -> Self {
|
||||
self.langid = Some(language.langid());
|
||||
self
|
||||
}
|
||||
}
|
||||
|
||||
// Genera la cabecera `Message-ID`, que los filtros de correo no deseado penalizan si falta. Sólo
|
||||
// tiene que ser única: la hora, un contador y el proceso lo garantizan sin depender del azar. El
|
||||
// dominio es el del remitente y no el nombre del equipo, que en un contenedor suele ser aleatorio y
|
||||
// también penalizan algunos filtros.
|
||||
fn message_id(domain: &str) -> String {
|
||||
static COUNTER: AtomicU64 = AtomicU64::new(0);
|
||||
let nanos = SystemTime::now()
|
||||
.duration_since(UNIX_EPOCH)
|
||||
.map_or(0, |elapsed| elapsed.as_nanos());
|
||||
let count = COUNTER.fetch_add(1, Ordering::Relaxed);
|
||||
format!("<{nanos:x}.{count:x}.{:x}@{domain}>", std::process::id())
|
||||
}
|
||||
|
||||
// Parte de un mensaje MIME: simple o compuesta por otras partes.
|
||||
enum Part {
|
||||
Single(SinglePart),
|
||||
Multi(MultiPart),
|
||||
}
|
||||
|
||||
// Compone una parte del tipo dado con `first` y el resto de partes, en ese orden.
|
||||
fn multipart(kind: MultiPartBuilder, first: Part, rest: Vec<Part>) -> Part {
|
||||
let mut multi = match first {
|
||||
Part::Single(part) => kind.singlepart(part),
|
||||
Part::Multi(multi) => kind.multipart(multi),
|
||||
};
|
||||
for part in rest {
|
||||
multi = match part {
|
||||
Part::Single(part) => multi.singlepart(part),
|
||||
Part::Multi(part) => multi.multipart(part),
|
||||
};
|
||||
}
|
||||
Part::Multi(multi)
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue