//! Correos electrónicos ([`Email`]). use pagetop::prelude::*; use crate::{Attachment, MailError, MailTemplate, Mailbox, layout, text, transport}; use lettre::Message; use lettre::message::header::{HeaderName, HeaderValue}; 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. Con /// la *feature* `queue`, `queue()` lo guarda en la cola de envío para el siguiente lote. 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. /// /// Por defecto, los correos llevan la cabecera `Auto-Submitted: auto-generated`: los envía la /// aplicación, no una persona, así que no deben recibir respuestas automáticas (avisos de /// ausencia...). Ver [`with_auto_submitted()`](Self::with_auto_submitted). /// /// # Ejemplo /// /// ```rust,no_run /// use pagetop::prelude::*; /// use pagetop_mail::prelude::*; /// /// async fn send_report(pdf: Vec) -> Result<(), MailError> { /// Email::new() /// .with_to("Ana Pérez ") /// .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, /// Dirección de respuesta, si se ha indicado. reply_to: Option, /// Destinatarios principales. to: Vec, /// Destinatarios en copia. cc: Vec, /// Destinatarios en copia oculta. bcc: Vec, /// Asunto. subject: String, /// Texto plano, si lo tiene. text: Option, /// HTML, si lo tiene: el contenido mientras se compone y el documento completo una vez enviado. html: Option, #[getters(skip)] html_is_document: bool, /// Archivos adjuntos e imágenes incrustadas. attachments: Vec, #[getters(skip)] langid: Option<&'static LanguageIdentifier>, /// Si lleva la cabecera `Auto-Submitted: auto-generated` (por defecto, sí). #[default = true] #[getters(copy)] auto_submitted: bool, } 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 (salvo con `transport = "log"`, que sólo escribe el correo en las trazas) o los /// destinatarios, si la entrega falla o no termina en el tiempo máximo /// (`mail.delivery_timeout_secs`, [`MailError::Timeout`]), o si ya hay demasiados correos /// esperando turno ([`MailError::Overloaded`]). 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). /// /// Sin la *feature* `queue`, los correos pendientes se pierden si la aplicación se detiene /// antes de enviarlos, y no se reintentan si fallan. Con ella, el correo se guarda primero en /// la cola de envío y se intenta enseguida, sin esperar al trabajo que la vacía: si falla por /// un error temporal, queda en la cola para reintentarlo (ver `queue()`). Si no se puede /// guardar en la cola, se envía igualmente sin ella y se avisa en las trazas. /// /// Si llegan más correos de los que el servidor despacha y ya hay demasiados esperando turno /// ([`MailError::Overloaded`]), sin la *feature* `queue` el correo se descarta, y con ella /// queda en la cola para el siguiente lote. pub fn send_later(self) { tokio::spawn(async move { let subject = self.subject.clone(); #[cfg(feature = "queue")] let result = crate::queue::send_later(self).await; #[cfg(not(feature = "queue"))] let result = self.send().await; if let Err(err) = result { trace::error!("Cannot send email \"{subject}\": {}", err.describe()); } }); } /// Guarda el correo en la cola de envío, que lo envía en el siguiente lote. Requiere la /// *feature* `queue`. /// /// Pensado para los envíos masivos (avisos a todos los usuarios, informes periódicos...): el /// trabajo `mail.queue` de `pagetop-cron` envía en cada ejecución, uno tras otro, como mucho /// `mail.queue.batch_size` correos, así que muchos correos no sobrecargan el equipo ni el /// servidor de correo. Para los que no pueden esperar al siguiente lote, como los de /// recuperación de contraseña, usa [`send_later()`](Self::send_later). /// /// El correo se completa y se compone al guardarlo, con el diseño común y en su idioma. Falla /// aquí por los mismos motivos que [`send()`](Self::send) antes de la entrega (direcciones o /// tipos MIME de los adjuntos no válidos, sin remitente o sin destinatarios), o si no se puede /// guardar en la base de datos. Ya en la cola, un fallo temporal se reintenta con una espera /// creciente, y un rechazo definitivo del servidor (SMTP 5xx) o el último intento fallido lo /// dejan como fallido. Los correos guardados sobreviven a un reinicio. /// /// La entrega es *al menos una vez*: si la aplicación se detiene justo después de que el /// servidor acepte un correo y antes de anotarlo como enviado, se volverá a enviar. Lo mismo /// ocurre si el servidor lo acepta pero tarda tanto en confirmarlo que se agota el tiempo /// máximo de la entrega ([`MailError::Timeout`]), o si se cancela el trabajo a mitad de una /// entrega (por su `timeout_secs` en `[cron.jobs."mail.queue"]` o por el tiempo máximo de /// espera al detener la aplicación). /// /// Con `transport = "log"` no se usa la cola: el correo se escribe enseguida en las trazas. /// /// # Ejemplo /// /// ```rust,no_run /// # use pagetop::prelude::*; /// # use pagetop_mail::prelude::*; /// async fn notify_all(addresses: Vec) -> Result<(), MailError> { /// for address in addresses { /// Email::new() /// .with_to(address) /// .with_subject("Parada programada") /// .with_text("El servicio se detendrá el sábado de 8:00 a 10:00.") /// .queue() /// .await?; /// } /// Ok(()) /// } /// ``` #[cfg(feature = "queue")] pub async fn queue(self) -> Result<(), MailError> { crate::queue::push(self).await } // 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 { 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()))); if self.auto_submitted { builder = builder.raw_header(auto_submitted_header()); } builder = builder.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::, _>>()?; 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::, _>>()?; 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) -> 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) -> Self { self.reply_to = Some(reply_to.into()); self } /// Añade un destinatario principal (`To`). pub fn with_to(mut self, to: impl Into) -> Self { self.to.push(to.into()); self } /// Añade un destinatario en copia (`Cc`). pub fn with_cc(mut self, cc: impl Into) -> 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) -> Self { self.bcc.push(bcc.into()); self } /// Establece el asunto. Los caracteres de control (saltos de línea, tabuladores...) se cambian /// por espacios: el asunto puede incluir datos de usuario, y una cabecera es una sola línea. pub fn with_subject(mut self, subject: impl Into) -> Self { self.subject = subject .into() .chars() .map(|c| if c.is_control() { ' ' } else { c }) .collect(); self } /// Establece el texto plano. pub fn with_text(mut self, text: impl Into) -> 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 } /// Indica si el correo lleva la cabecera `Auto-Submitted: auto-generated` (RFC 3834), que lo /// marca como enviado por un programa. Por defecto la llevan todos: así los contestadores /// automáticos que siguen el RFC (avisos de ausencia, de vacaciones...) no responden a la /// dirección del remitente. /// /// Quítala (`false`) en los correos que escribe una persona y que deben tratarse como suyos, /// como los de un formulario de contacto dirigidos a una dirección de soporte: hay sistemas de /// atención al cliente que suspenden o rechazan los correos marcados como automáticos, para no /// abrir incidencias con ellos. pub fn with_auto_submitted(mut self, auto_submitted: bool) -> Self { self.auto_submitted = auto_submitted; 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()) } // Cabecera `Auto-Submitted: auto-generated` (ver `Email::with_auto_submitted()`). fn auto_submitted_header() -> HeaderValue { HeaderValue::new( HeaderName::new_from_ascii_str("Auto-Submitted"), "auto-generated".to_owned(), ) } // 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 { 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) }