# API reference Import the public API from `@locus-ui/mail`. See [getting started](/docs/mail) for a complete template and [sending emails](/docs/mail/sending) for an end-to-end send. ## email `email({ id, name, template, mapToSend })` creates a typed email definition. - `id`: a lowercase slug, such as `welcome`, `account.created`, or `password-reset`. - `name`: a nonempty display name. - `template`: a React component receiving the mapped props. - `mapToSend(input)`: returns or resolves to `{ data, sendOptions, text }`, or `null` to skip. `sendOptions.subject` and `text` must be nonempty strings. Subjects cannot contain line breaks. The returned definition exposes: - `prepare(input)`: run the mapper and validate the prepared message shape, or return `null`. - `render(input)`: prepare and render HTML, returning `{ subject, html, text, sendOptions }` or `null`. - `renderPreview(props)`: render with explicit props without running the mapper. `EmailInput`, `EmailData`, `EmailDefinition`, and `EmailTemplate` are exported types for typed integrations. ## renderPreview `renderPreview(Component, props)` renders an email component directly. It returns an object containing `html`. It does not load application data or send a message. ```tsx import { renderPreview } from "@locus-ui/mail"; import WelcomeEmail from "./emails/welcome.email"; const { html } = renderPreview(WelcomeEmail, { firstName: "Wally" }); ``` ## createMailer `createMailer({ transport, from? })` returns a server-only mailer with `send(definition, input, overrides?)`. `overrides` accepts `from`, `to`, `cc`, `bcc`, and `replyTo`. The default sender is applied first, followed by mapped send options, followed by overrides. Delivery addresses are validated before rendering. `SendResult` is a union of a sent receipt and a skipped result: ```ts type SendResult = | { status: "sent"; templateId: string; provider: string; id: string } | { status: "skipped"; templateId: string }; ``` ## createResendTransport `createResendTransport({ apiKey, fetch? })` creates the included Resend transport. `apiKey` must be nonempty and contain no whitespace. The optional `fetch` allows an alternative request implementation. Requests use a 30-second timeout. Provider failures throw `ResendDeliveryError`, with an HTTP `status` when available. Sending through a mailer wraps that error in a `MailSendError` with `stage: "provider"`. ## MailTransport Implement this interface to use a different delivery provider: ```ts import type { MailTransport } from "@locus-ui/mail"; const transport: MailTransport = { name: "my-provider", async send(message) { // Deliver message.html and message.text through your provider. // Return the provider's actual, nonempty message ID. throw new Error("Implement your provider integration here"); }, }; ``` `DeliveryMessage` contains `from`, normalized `to` addresses, optional `cc`, `bcc`, and `replyTo` arrays, `subject`, `html`, `text`, and the original `sendOptions`. The transport must resolve to a `DeliveryReceipt` containing a nonempty `id` string. ## defineConfig `defineConfig(config)` types the local preview configuration. `MailConfig` supports optional `root`, `path`, `port`, and `previewSend: { from, transport }` fields. See [local preview](/docs/mail/preview) for configuration and CLI examples. Environment variables must be available before the CLI starts. `.env` files are not loaded automatically. ## MailSendError `MailSendError` exposes `templateId`, `cause`, and a `stage` of `preparation`, `validation`, `rendering`, or `provider`. Handle application-specific errors at the calling boundary and check provider acceptance before retrying an uncertain send.