# Sending emails A template is a reusable React view. An email definition connects that view to application inputs. A mailer validates delivery options, renders the HTML, and passes the message to a transport. ## Configure a mailer Create a Resend API key and verify your sending domain. Set `RESEND_API_KEY` and `MAIL_FROM` (for example, `Your Domain `) in your server environment. Then you can set up your mailer. ```ts // mailer.ts import { createMailer, createResendTransport } from "@locus-ui/mail"; export const mailer = createMailer({ from: process.env.MAIL_FROM!, transport: createResendTransport({ apiKey: process.env.RESEND_API_KEY!, }), }); ``` ## Define the email Set up an email template like the one from [getting started](/docs/mail). The `email` mapper can then be used to construct your emails so they can be sent. The mapper owns validation, data loading, the recipient, the subject, and the plain-text body. TypeScript infers the send input from its parameter. ```ts // send-welcome-email.ts import { email } from "@locus-ui/mail"; import { mailer } from "./mailer"; import WelcomeEmail from "./emails/welcome.email"; type WelcomeInput = { firstName: string; to: string; }; const welcome = email({ id: "welcome", name: "Welcome", template: WelcomeEmail, mapToSend: ({ firstName, to }: WelcomeInput) => ({ data: { firstName }, sendOptions: { to, subject: `Welcome, ${firstName}!`, }, text: `We're glad to see you here, ${firstName}!`, }), }); const result = await mailer.send(welcome, { firstName: "Wally", to: "wally@example.com", }); ``` The mapper may be asynchronous. Return `null` when an application condition means the email should be skipped. Preview props are never used as a fallback. ## Delivery overrides The third argument to `mailer.send` can override `from`, `to`, `cc`, `bcc`, and `replyTo`: ```ts await mailer.send( welcome, { firstName: "Wally", to: "wally@example.com", }, { replyTo: "support@example.com", }, ); ``` The mailer's default sender is applied first, then the definition's send options, then these overrides. Recipient fields accept a string or an array of strings. ## Results and errors A successful send returns `status: "sent"`, `templateId`, `provider`, and the provider's message `id`. This means the provider accepted the request. It does not confirm inbox delivery. If the mapper returns `null`, the result is `status: "skipped"` with the `templateId`, and no message is sent. Failures throw `MailSendError`. Its `stage` is `preparation`, `validation`, `rendering`, or `provider`. Inspect `cause` for the original error. A failed request may have reached the provider, so check provider logs before retrying. ## Use another provider Implement the [MailTransport interface](/docs/mail/api#mailtransport) and pass it to `createMailer`. Templates and mappers can remain the same when the transport changes.