@lara-node/mail

Multi-driver mailer (SMTP, log, array, failover) with a Mailable base class, queued mail, and full TypeScript types.

Installation

pnpm add @lara-node/mail

Quick Start

import { Mail } from "@lara-node/mail";
import { WelcomeMail } from "./app/Mail/WelcomeMail";

// Send immediately
await Mail.to("[email protected]").send(new WelcomeMail(user));

// Queue for background delivery
await Mail.to("[email protected]").queue(new WelcomeMail(user));

// Schedule for later
await Mail.to("[email protected]").later(new WelcomeMail(user), 300); // 5 min delay

Creating a Mailable

Extend the Mailable base class and implement build():

import { Mailable } from "@lara-node/mail";

interface User {
  name: string;
  email: string;
}

export class WelcomeMail extends Mailable {
  constructor(private readonly user: User) {
    super();
  }

  build(): this {
    return this.subject(`Welcome, ${this.user.name}!`)
      .from("[email protected]", "My App")
      .html(`<h1>Hello ${this.user.name}</h1><p>Thanks for signing up.</p>`)
      .text(`Hello ${this.user.name}. Thanks for signing up.`);
  }
}

Mailable fluent methods

All methods return this for chaining and must be called inside build().

this.subject("Your order has shipped");
this.from("[email protected]");
this.from("[email protected]", "My App");
this.html("<p>Hello</p>");
this.text("Hello");
this.attach("/path/to/invoice.pdf");
this.attach("/path/to/file.csv", { filename: "report.csv", contentType: "text/csv" });
this.cc("[email protected]");
this.bcc("[email protected]");
this.replyTo("[email protected]");
this.priority("high"); // 'high' | 'normal' | 'low'
this.tag("transactional"); // tag for analytics / filtering
this.mailer("smtp"); // override the default mailer for this message
this.with({ code: "123456" }); // pass data to the template (if using a view engine)

Mail Facade

Mail.to(address)

Returns a PendingMail builder.

Mail.to("[email protected]");
Mail.to(["[email protected]", "[email protected]"]);
Mail.to({ address: "[email protected]", name: "Alice" });

PendingMail methods

await pending.send(mailable); // send synchronously
await pending.queue(mailable); // dispatch to queue
await pending.later(mailable, delaySeconds); // dispatch after a delay

Sending to multiple recipients

const users = await User.all();

for (const user of users) {
  await Mail.to(user.email).queue(new NewsletterMail(user));
}

Multiple Mailers

Configure multiple mailers in config/mail.ts:

import { setConfig } from "@lara-node/core";

setConfig("mail", {
  default: "smtp",
  mailers: {
    smtp: {
      transport: "smtp",
      host: process.env.MAIL_HOST,
      port: Number(process.env.MAIL_PORT ?? 587),
      username: process.env.MAIL_USERNAME,
      password: process.env.MAIL_PASSWORD,
      encryption: process.env.MAIL_ENCRYPTION ?? "tls",
    },
    log: {
      transport: "log",
    },
    failover: {
      transport: "failover",
      mailers: ["smtp", "log"],
    },
  },
  from: {
    address: process.env.MAIL_FROM_ADDRESS ?? "[email protected]",
    name: process.env.MAIL_FROM_NAME ?? "My App",
  },
});

Override the mailer for a single message:

this.mailer("log"); // inside build()

MailServiceProvider

import { MailServiceProvider } from "@lara-node/mail";

app.register(MailServiceProvider);

Environment Variables

| Variable | Default | Description | | ----------------------- | ------- | ----------------------------------------------- | | MAIL_MAILER | smtp | Default mailer name | | MAIL_HOST | — | SMTP host | | MAIL_PORT | 1025 | SMTP port | | MAIL_USERNAME | — | SMTP username | | MAIL_PASSWORD | — | SMTP password | | MAIL_ENCRYPTION | — | tls, ssl, or empty | | MAIL_FROM_ADDRESS | — | Default sender address | | MAIL_FROM_NAME | — | Default sender display name | | MAIL_FAILOVER_MAILERS | — | Comma-separated mailers for the failover driver |

Notes

• The log driver writes mail content to the application log rather than sending — useful during development.
• The array driver stores sent messages in memory and exposes them for inspection in tests.
• Queued mail requires a configured queue connection. See @lara-node/queue.
• attach() resolves paths relative to process.cwd().