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 <mail@your-domain.com>) in your server environment. Then you can set up your mailer.
// 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. 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.
// 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:
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 and pass it to createMailer. Templates and mappers can remain the same when the transport changes.