---
name: lunora-setup-mail
description: Adds transactional email to a Lunora app. Use for sending mail (verification, password reset, invites, notifications) via `lunora registry add mail`, the `sendEmail` / `queueEmail` actions, the `SEND_EMAIL` Cloudflare Email Workers binding, Resend, React email templates, and the dev mail catcher.
---

# Lunora Setup Mail

Wire transactional email into a Lunora app using the `mail` registry item, which
is built on `@lunora/mail` (a Cloudflare Email Workers transport with
header-injection-safe address handling) and exposes a `sendEmail` `internalAction`
plus a fire-and-forget `queueEmail` `internalAction` — server-only, because a
client-callable general-purpose mailer is an open relay. In dev, every send is captured into the
Studio Mail tab instead of going out.

## When to Use

- Sending app→user mail: invites, notifications, receipts.
- Delivering verification / password-reset mail from `@lunora/auth`.
- Using a React (`react-email`) template or a hosted provider (Resend).

## When Not to Use

- The project has no Lunora backend yet — use `lunora-quickstart` first.
- Mail is already installed and you just want to send — call
  `ctx.runAction(internal.mail.sendEmail, …)` from a server handler.

## Workflow

1. Add the `mail` item.
2. Configure the `SEND_EMAIL` binding (or a provider) and `MAIL_FROM`.
3. Regenerate types with `lunora codegen`.
4. Send mail from a server function; render a React template if needed.

## Step 1: Add the item

```bash
lunora registry add mail
```

This:

1. Adds `@lunora/mail` and `@lunora/server` to `package.json` (run
   `pnpm install` afterwards).
2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail`
   **`internalAction`s**) into your project — it is **yours** to edit.
3. Adds a `send_email` binding (`SEND_EMAIL`, with a `destination_address`
   placeholder) to `wrangler.jsonc` and scaffolds `MAIL_FROM` (the default
   sender) into `.dev.vars`.

## Step 2: Configure delivery

| Name             | Where                                | Notes                                                                             |
| ---------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
| `SEND_EMAIL`     | `wrangler.jsonc` → `send_email[]`    | Cloudflare Email Workers binding. Single-recipient; only verified destinations.   |
| `MAIL_FROM`      | var (`.dev.vars` / `wrangler.jsonc`) | Default sender address.                                                           |
| `RESEND_API_KEY` | secret (optional)                    | Use a hosted provider instead — pass `apiKey` to `createMailer` in `lunora/mail`. |

For production with Cloudflare Email Workers, set up
[Email Routing](https://developers.cloudflare.com/email-routing/): verify a
destination address and replace the `REPLACE_ME@example.com` placeholder. Prefer
Resend? Pass `apiKey` (or a custom `transport`) to `createMailer` in your copied
`lunora/mail/index.ts`.

In `lunora dev` (`WORKER_ENV=development`) the scaffold swaps in `@lunora/mail`'s
**capture transport** automatically: every send — including `@lunora/auth`'s
verification and forgot-password mail — is intercepted and surfaced in the
**Studio Mail tab**. Nothing leaves your machine and no provider setup is needed.

## Step 3: Regenerate types

```bash
lunora codegen
```

The functions surface in the generated **`internal`** (server-only) namespace as
`internal.mail.sendEmail` and `internal.mail.queueEmail` — they are deliberately
**not** in the client-reachable `api`.

## Step 4: Send mail

### From another function

`sendEmail` is an **`internalAction`** (sending is non-transactional network
I/O). From a mutation, schedule it as a follow-up so the request is not blocked:

```ts
import { internalMutation, v } from "#lunora/_generated/server.js";

import { internal } from "./_generated/api";

export const inviteUser = internalMutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
    // ...authenticate the caller and persist the invite, then send the mail as a
    // follow-up action. The recipient is decided server-side — never forward a
    // client-chosen `to`/`from`/`html` straight through.
    await ctx.scheduler.runAfter(0, internal.mail.sendEmail, {
        to: email,
        subject: "You're invited",
        html: "<p>Click the link to join.</p>",
    });
});
```

### Not from a client

There is no `client.action("mail/sendEmail", …)` path, and adding one is the
mistake this item exists to prevent: a general-purpose mailer that lets the
caller pick recipient, subject and body is an open relay for phishing through
your verified domain. If you need a client-callable send, write a
_purpose-specific_ public `action` that takes only safe business inputs (e.g.
`{ orderId }`), checks `ctx.auth`/RBAC, derives the recipient server-side,
rate-limits it (`@lunora/ratelimit`), and calls `internal.mail.sendEmail`.

### With a React email template

React elements are not JSON-serializable across the RPC boundary, so the
`sendEmail` args take `html` / `text`. To use a `react-email` template, render it
where you call the mailer — edit `lunora/mail/index.ts` to pass `react` straight
into `mailer.send`:

```ts
import { createMailer } from "@lunora/mail";
import { env } from "cloudflare:workers";

import { WelcomeEmail } from "./emails/Welcome";

await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM as string }).send({
    to: "alice@example.com",
    subject: "Welcome",
    react: <WelcomeEmail name="Alice" />,
});
```

## Common Pitfalls

1. **Expecting prod email to "just work".** Dev captures into the Studio;
   production needs the `SEND_EMAIL` binding (a verified destination) or
   `RESEND_API_KEY`.
2. **Calling `sendEmail` from the client, or as a query/mutation.** It is an
   `internalAction` — invoke it via `ctx.runAction` / `ctx.scheduler.runAfter`
   from a server handler. A client `client.action("mail/sendEmail", …)` is not
   reachable and answers `FUNCTION_NOT_FOUND`.
3. **Using `queueEmail` without a Queue binding.** It requires a Cloudflare
   Queue producer binding; until you add one, `@lunora/mail` throws
   `` `queue` binding is required for mailer.queue() ``. The item does not add
   the Queue for you — see the `mail` README's "Queueing" section.
4. **Passing a React element through the action args.** Render it inside the
   mailer (`mailer.send({ react })`), not across the RPC boundary.

## Checklist

- [ ] `lunora registry add mail` run, `pnpm install` done.
- [ ] `SEND_EMAIL` binding configured (verified destination) or
      `RESEND_API_KEY` set; `MAIL_FROM` set.
- [ ] `lunora codegen` run so `internal.mail.*` is generated.
- [ ] Mail sent from a server function (`ctx.scheduler.runAfter` / `ctx.runAction`
      with `internal.mail.sendEmail`) — never from the client.
- [ ] Verified the send appears in the Studio Mail tab in dev.