Digging deeper
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.
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().