Mailer

The @talosjs/mailer component sends transactional emails. The mailer renders a React node to HTML on the server, so your email bodies are plain components rather than strings you concatenate by hand. Every sender implements the same IMailer interface, which is just a single send method, so callers stay identical no matter how the mail is delivered. MailerLayout provides a styled header/body/footer shell to build templates on.

What the mailer gives you

Every mailer implements IMailer (send) and is registered with a decorator, so you resolve and inject it like any other service. Email bodies are React nodes, rendered to HTML with renderToString, which means you compose them the way you compose UI. The MailerLayout component ships with Header, Body, and Footer subcomponents and email-safe defaults. Credentials and the default sender come from environment variables, and any send can override them. The packaged ResendMailer delivers through the Resend API.

How it works

You resolve a mailer from the container and call send. The mailer renders the content React node to HTML, resolves the sender (from the call or the environment), and delivers the message.

Member	Purpose
`send(config)`	Render `content` and send the email. Resolves to `void`.

The config object passed to send:

Field	Type	Purpose
`to`	`string[]`	Recipient email addresses.
`subject`	`string`	Email subject line.
`content`	`React.ReactNode`	Body rendered to HTML server-side.
`from`	`{ name: string; address: string }`	Optional sender override; falls back to the environment defaults.
`attachments`	`MailerAttachmentType[]`	Optional files to attach.

The sender is resolved per call: config.from wins, otherwise MAILER_SENDER_NAME and MAILER_SENDER_ADDRESS are used. If neither yields a name and address, send throws. Each entry in attachments is a MailerAttachmentType:

Field	Type	Purpose
`filename`	`string`	Name of the attached file.
`content`	`string \| Buffer`	File content, as a base64 string or `Buffer`.
`path`	`string`	Remote path the attachment is hosted at, used instead of `content`.
`contentType`	`string`	Content type of the attachment. Derived from `filename` when omitted.
`contentId`	`string`	Content ID for an inline attachment, referenced in the HTML content using the `cid:` prefix.

Environment variables

Variable	Required	Purpose
`RESEND_API_KEY`	Yes	API key used by `ResendMailer` to authenticate with Resend.
`MAILER_SENDER_NAME`	No	Default sender name. Required at send time unless `from.name` is provided.
`MAILER_SENDER_ADDRESS`	No	Default sender address. Required at send time unless `from.address` is provided.

RESEND_API_KEY=re_xxxxxxxx
MAILER_SENDER_NAME=Acme
MAILER_SENDER_ADDRESS=hello@acme.com

Decorator and usage

`@decorator.mailer()`

Registers a mailer class with the container. It accepts an optional scope (defaults to singleton). ResendMailer is already decorated; use the decorator on your own mailer classes so they can be resolved and injected. Resolve the mailer from the container and send an email. The body is just a React node:

import { container } from "@talosjs/container";
import { MailerLayout, ResendMailer } from "@talosjs/mailer";

const mailer = container.get(ResendMailer);

await mailer.send({
  to: ["user@example.com"],
  subject: "Welcome to Acme!",
  content: (
    <MailerLayout>
      <MailerLayout.Header />
      <MailerLayout.Body>
        <h1>Welcome aboard</h1>
        <p>Thanks for signing up.</p>
      </MailerLayout.Body>
      <MailerLayout.Footer />
    </MailerLayout>
  ),
});

Override the sender per call when a message should come from a specific address:

await mailer.send({
  to: ["user@example.com"],
  subject: "Important update",
  content: <UpdateEmail />,
  from: { name: "Support Team", address: "support@acme.com" },
});

A typical mailer wraps a template and delegates to the injected ResendMailer. Register it with the decorator and inject the packaged sender directly:

import { inject } from "@talosjs/container";
import { decorator, ResendMailer } from "@talosjs/mailer";
import { type WelcomeMailerPropsType, WelcomeMailerTemplate } from "./WelcomeMailerTemplate";

@decorator.mailer()
export class WelcomeMailer {
  constructor(
    @inject(ResendMailer)
    private readonly mailer: ResendMailer,
  ) {}

  public async send(config: {
    to: string[];
    data?: WelcomeMailerPropsType;
  }): Promise<void> {
    await this.mailer.send({
      to: config.to,
      subject: "Welcome",
      content: WelcomeMailerTemplate(config.data),
    });
  }
}

Exceptions

The component throws MailerException when it is misconfigured or a send cannot complete. It carries a machine-readable key, a human-readable message, and a data object.

Key	When
`API_KEY_REQUIRED`	`ResendMailer` is constructed with no `RESEND_API_KEY` set.
`EMAIL_SEND_FAILED`	`send` is called with no resolvable sender name (no `from.name` and no `MAILER_SENDER_NAME`).
`EMAIL_OPERATION_FAILED`	`send` is called with no resolvable sender address (no `from.address` and no `MAILER_SENDER_ADDRESS`).

import { MailerException } from "@talosjs/mailer";
import { container } from "@talosjs/container";
import { ResendMailer } from "@talosjs/mailer";

const mailer = container.get(ResendMailer);

try {
  await mailer.send({ to: ["user@example.com"], subject: "Hi", content: <Email /> });
} catch (error) {
  if (error instanceof MailerException) {
    logger.error(`Mailer error [${error.key}]: ${error.message}`, error.data);
  } else {
    throw error;
  }
}

Working with mailers

Configure MAILER_SENDER_NAME and MAILER_SENDER_ADDRESS once so every send has a fallback, then override from only when a message needs a different address. Compose bodies on MailerLayout (Header, Body, Footer) for email-safe markup instead of raw HTML strings, and keep your templates as props-driven functions: pass data in, return a React node, and they render in tests without sending anything. It helps to wrap a template per email type. A dedicated mailer like WelcomeMailer, delegating to the injected ResendMailer, keeps its subject, template, and props in one place. Catch MailerException at send sites and read error.key to tell a configuration problem apart from a delivery one, and never leak credentials in the process. Always resolve mailers through the container rather than constructing them, so credentials and defaults stay wired consistently.

CLI command

Scaffold a mailer, its JSX template, and their tests with the generator. It writes the class under modules/<module>/src/mailers/<Name>Mailer.ts, the template alongside it, and installs @talosjs/mailer if it is missing.

# Interactive: prompts for the name
talos mailer:create

# Provide the name
talos mailer:create --name=Welcome

# Target a module and overwrite
talos mailer:create --name=Welcome --module=auth --override

Option	Description	Default
`--name`	Mailer class name. The `Mailer` suffix is appended automatically.	Prompted if omitted
`--module`	Target module the files are generated into.	`shared`
`--override`	Overwrite an existing mailer without prompting.	`false`

The generated mailer wraps its template and delegates to the injected IMailer, ready for you to refine the subject and props.

import { inject } from "@talosjs/container";
import { decorator, ResendMailer } from "@talosjs/mailer";
import { type WelcomeMailerPropsType, WelcomeMailerTemplate } from "./WelcomeMailerTemplate";

@decorator.mailer()
export class WelcomeMailer {
  constructor(
    @inject(ResendMailer)
    private readonly mailer: ResendMailer,
  ) {}

  public async send(config: {
    to: string[];
    data?: WelcomeMailerPropsType;
  }): Promise<void> {
    await this.mailer.send({
      to: config.to,
      subject: "Welcome",
      content: WelcomeMailerTemplate(config.data),
    });
  }
}

The companion template is a props-driven function built on MailerLayout:

import { MailerLayout } from "@talosjs/mailer";

export type WelcomeMailerPropsType = {
  link: string;
};

export const WelcomeMailerTemplate = (props?: WelcomeMailerPropsType) => (
  <MailerLayout>
    <MailerLayout.Header />
    <MailerLayout.Body>
      <a href={props?.link}>Login</a>
    </MailerLayout.Body>
    <MailerLayout.Footer />
  </MailerLayout>
);

See mailer:create for the full command reference.

Use with Claude and Codex

The generator ships a matching mailer:create skill. It runs the scaffold, then guides your AI agent through completing the mailer: refining the send config, filling in the template props, and wiring up its tests. Initialize the skills once for your agent.

Claude
Codex

talos agent:skills:create

Then ask Claude in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a mailer that sends a welcome email after sign-up.

talos agent:skills:create

Then ask Codex in natural language. It maps the request to the generator, runs it, and fills in the implementation:

Prompt

Create a mailer that sends a welcome email after sign-up.

For example, the prompt above maps to mailer:create --name=Welcome, then builds the welcome template and completes the send method.

Getting Started

AI

Framework

Command Line

What the mailer gives you

How it works

Environment variables

Decorator and usage

`@decorator.mailer()`

Exceptions

Working with mailers

CLI command

Use with Claude and Codex

​What the mailer gives you

​How it works

​Environment variables

​Decorator and usage

​@decorator.mailer()

​Exceptions

​Working with mailers

​CLI command

​Use with Claude and Codex

What the mailer gives you

How it works

Environment variables

Decorator and usage

`@decorator.mailer()`

Exceptions

Working with mailers

CLI command

Use with Claude and Codex