Smeltery
Get started

Digging deeper

v0.1

Mail

Mail (smeltery::mail) is wired with .mail() in bootstrap/app.rs (the trait is smeltery::mail::MailExt, in the prelude). A mail class is a Mold template struct that also implements Mailable: the template is the HTML body, the struct's fields are its variables, and envelope() says who gets it. smeltery make:mail Welcome creates app/mail/welcome.rs and resources/views/mail/welcome.mold.html (an HTML mail with inline styles) and adds the module to app/mail/mod.rs; new apps install mail and have the MAIL_* keys in .env.

rust
use smeltery::prelude::*;

#[derive(Mold)]
#[mold("mail/welcome")]                 // resources/views/mail/welcome.mold.html
pub struct Welcome {
    pub name: String,
    pub email: String,
}

impl Mailable for Welcome {
    fn envelope(&self) -> Envelope {
        Envelope::new()
            .to(self.email.as_str())        // also "Ada <ada@example.com>" or ("ada@example.com", "Ada")
            .subject(format!("Welcome, {}!", self.name))
    }
}

async fn register(mailer: Mailer, Form(form): Form<RegisterForm>) -> Result<Redirect> {
    mailer.send(Welcome { name: form.name, email: form.email }).await?;
    Ok(Redirect::to("/"))
}

Envelope has to, cc, bcc, reply_to, from (instead of MAIL_FROM_ADDRESS / MAIL_FROM_NAME) and subject. Besides envelope(), a Mailable may implement text() (the plain-text part, e.g. from a second template rendered with smeltery::mail::render; by default it is made from the HTML: tags dropped, links as text (url)) and attachments() (Attachment::from_bytes(name, bytes), Attachment::from_path(path)). Mail templates render like views (from the files with hot reload in debug builds, compiled in release builds); route("name") gives absolute URLs (APP_URL + path) in mail.

Mailer is a handler argument, or Mailer::of(&app) elsewhere: send(mail) renders on a blocking thread and hands the mail to the transport, render(mail) returns the rendered Email, and send_email(email) sends an Email built by hand (Email::new(envelope).html(…).text(…).attach(…)). With Watchfire, mailer.queue(mail) / queue_later(mail, delay) (the trait smeltery::watchfire::mail::QueueMail, in the prelude) render the mail now and send it from a queue worker, retried like any job (the job smeltery-send-mail is registered when the app has both .mail() and .agents(…)).

Variable Default Meaning
MAIL_MAILER log smtp, log (the mail is written to the log at info, target smeltery::mail: sender, recipients, subject and text part; outside local development (APP_ENV local or testing with an APP_URL on this machine) only sender, recipients and subject, with a note that the body was withheld because it can carry secrets such as reset links, and a warning at boot) or fake; always fake under APP_ENV=testing
MAIL_HOST 127.0.0.1 the SMTP server
MAIL_PORT 465 for tls, 587 for starttls, 25 for none its port
MAIL_USERNAME, MAIL_PASSWORD empty the SMTP login (none when the username is empty); the password is never logged
MAIL_ENCRYPTION starttls tls (TLS from the start), starttls (an upgrade the server must offer), none (plain SMTP; with a MAIL_USERNAME only for a MAIL_HOST on this machine, since the password would cross the network in clear: anywhere else the mailer refuses to start)
MAIL_TLS_CA empty a PEM file (relative to the app root) of extra CA certificates to trust, for an SMTP server with a private CA
MAIL_TIMEOUT 10 seconds per SMTP step; a whole send gives up after four times that
MAIL_FROM_ADDRESS, MAIL_FROM_NAME hello@example.com, APP_NAME the default sender

SMTP runs on lettre's Tokio transport with rustls (ring) and the platform's certificate verifier; MAIL_TLS_CA adds certificates to the platform's trusted roots. A server certificate that is not trusted fails the send before any login. A failed send is an error for the caller and a warn log line.

Testing: under APP_ENV=testing mail goes to a fake mailbox: Mailer::of(app.app())?.mailbox() (or Mailer::fake(app.app()) on an app without .mail()) returns it, with sent(), emails(), sent_of::<Welcome>(), assert_sent::<Welcome>(|mail, email| mail.name == "Ada"), assert_sent_count::<T>(n), assert_sent_to(address) and assert_nothing_sent().

↑↓ moveEnter openEsc close