Mailers

Relevant source files

The following files were used as context for generating this wiki page:

• src/mailer/mod.rs
• src/mailer/template.rs
• loco-new/base_template/src/mailers/auth.rs
• src/boot.rs
• src/cli.rs
• docs-site/content/casts/006-mailers.md
• loco-new/tests/templates/mailer.rs

Mailers in the Loco framework provide an integrated system for composing, templating, and sending emails. The system is designed to offer a seamless developer experience by supporting multiple providers, server-side template rendering, and asynchronous background processing out of the box.

The architecture separates the concerns of email composition (Mailers), content generation (Templates), and transmission (Email Senders). By default, mailers leverage the internal background worker system to ensure that email delivery does not block the main application request-response cycle.

Sources: docs-site/content/casts/006-mailers.md:1-5, src/mailer/mod.rs:1-6

Core Architecture

The mailer system is built around the Mailer trait and the Email data structure. When a mailer is invoked, it typically renders a template and then dispatches an Email object to a MailerWorker.

Data Structures

The following table describes the primary data structures used to define email content and delivery parameters:

Structure	Description	Key Fields
Email	Represents the final processed email ready for sending.	from, to, subject, text, html, headers
Args	Arguments used to specify dynamic details for a mailer.	to, locals (JSON), cc, bcc, reply_to
EmailHeaders	Custom SMTP headers for tracking or threading.	message_id, in_reply_to, references

Sources: src/mailer/mod.rs:21-61

The Mailer Trait

The Mailer trait defines the interface for all application mailers. It provides default implementations for sending emails either directly or via templates.

• mail: Takes an Email struct and enqueues it for background processing.
• mail_template: Combines a directory of templates with dynamic JSON "locals" to render and then send an email.

Sources: src/mailer/mod.rs:80-117

Background Processing

Loco uses a specialized MailerWorker to handle email transmission asynchronously. This worker is automatically registered during application boot if a background queue is configured.

Templates and Rendering

Loco utilizes the Tera engine for email templating. Templates are typically organized in directories containing three specific files: subject.t, html.t, and text.t.

Template Components

The Template struct manages the rendering of these files by injecting a JSON locals object into the templates.

• subject.t: Renders the email subject line.
• html.t: Renders the rich-text HTML version of the email.
• text.t: Renders the plain-text fallback version.

Sources: src/mailer/template.rs:17-64

Implementation Example: Auth Mailer

The framework includes base templates for common authentication tasks such as welcome emails and password resets. These utilize include_dir! to embed templates into the binary.

pub async fn send_welcome(ctx: &AppContext, user: &users::Model) -> Result<()> {
    Self::mail_template(
        ctx,
        &welcome,
        mailer::Args {
            to: user.email.clone(),
            locals: json!({
              "name": user.name,
              "verifyToken": user.email_verification_token,
              "host": ctx.config.server.full_url()
            }),
            ..Default::default()
        },
    )
    .await?;
    Ok(())
}

Sources: loco-new/base_template/src/mailers/auth.rs:17-38

Configuration and Tooling

Configuration Options

Mailers are configured via the application's environment YAML files (e.g., development.yaml).

Key	Type	Description
mailer.stub	Boolean	If true, emails are intercepted and logged instead of sent.
mailer.smtp.enable	Boolean	Enables SMTP delivery.
mailer.smtp.host	String	SMTP server hostname (e.g., "localhost").
mailer.smtp.port	Integer	SMTP server port (default: 1025).
mailer.smtp.secure	Boolean	Whether to use a secure connection.

Sources: loco-new/tests/templates/mailer.rs:25-50, src/boot.rs:592-604

CLI Integration

Loco provides CLI commands to generate new mailers, which creates the necessary directory structure and boilerplate code.

# Generate a new mailer
$ cargo loco generate mailer welcome_notification

Sources: src/cli.rs:341-344, src/cli.rs:530

Initialization Flow

The application boot sequence initializes the EmailSender based on the provided configuration.

Summary

The Mailers system in Loco is a "batteries-included" feature that streamlines communication within business applications. By combining Tera templating, background worker integration, and flexible delivery providers (SMTP or Stub), it allows developers to implement complex email workflows with minimal configuration. The use of embedded directories via include_dir! ensures that email templates are compiled into the final binary, maintaining the framework's "single binary deployment" philosophy.

Sources: src/mailer/mod.rs:1-10, docs-site/content/_index.md:39-41