Import the public API from @locus-ui/mail. See getting started for a complete template and sending emails for an end-to-end send.
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.
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:
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:
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 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.