Email

Transactional email is sent by packages/mail (@repo/mail). Templates are React Email components rendered to HTML and plain text, then handed to one provider.

Provider

packages/mail/src/provider/index.ts is a single line:

export * from './zeptomail';

So ZeptoMail is the active provider. The folder also contains adapters for Resend, Postmark, Mailgun, Plunk, Nodemailer (SMTP) and a console logger. They are not selected by configuration. Switching provider means changing that export and redeploying.

ZeptoMail

packages/mail/src/provider/zeptomail.ts posts JSON to the ZeptoMail send API.

Detail	Value
URL	`ZEPTOMAIL_API_URL`, or the ZeptoMail v1.1 email endpoint by default
Auth	`Authorization: Zoho-enczapikey` followed by `ZEPTOMAIL_TOKEN`
Body	`from`, `to`, `cc`, `bcc`, `reply_to`, `subject`, `htmlbody`, `textbody`
Sender	The `from` argument, or `MAIL_FROM`
Failure	A non-2xx response is logged and the handler throws “Could not send email”

parseAddress accepts both a bare address and the Name <address> form, so MAIL_FROM can carry a display name.

Environment variables

Variable	Used by	Purpose
`MAIL_FROM`	all providers	Default sender.
`ZEPTOMAIL_TOKEN`	ZeptoMail	Send token.
`ZEPTOMAIL_API_URL`	ZeptoMail	Optional override of the API URL.
`RESEND_API_KEY`	Resend adapter	Unused while ZeptoMail is active.
`POSTMARK_SERVER_TOKEN`	Postmark adapter	Unused.
`MAILGUN_API_KEY`, `MAILGUN_DOMAIN`	Mailgun adapter	Unused.
`PLUNK_API_KEY`	Plunk adapter	Unused.
`MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASS`	Nodemailer adapter	Unused.

These are read straight from process.env inside the package. They are not part of the validated env schema in apps/core-api/src/config.ts, so a missing ZEPTOMAIL_TOKEN does not stop the API from booting. It shows up only as failed sends.

`sendEmail`

packages/mail/src/lib/send.ts. Two call shapes:

await sendEmail({
  to: 'coach@example.com',
  locale: 'he',
  templateId: 'teamInvitation',
  context: { url, name, studioName, inviterName, roleTitle },
});

await sendEmail({
  to: 'coach@example.com',
  subject: 'Plain subject',
  text: 'Plain body',
  html: '<p>Plain body</p>',
});

Parameter	Notes
`to`	One recipient.
`from`	Optional. Defaults to `MAIL_FROM`.
`locale`	Optional. Defaults to the i18n default locale, `he`.
`templateId` and `context`	Render a template. `context` is type-checked against the template’s props.
`subject`, `text`, `html`	Send raw content with no template.

It never throws

try {
  await send({ to, from, subject, text, html });
  return true;
} catch (e) {
  logError('Failed to send email', e);
  return false;
}

sendEmail returns false on a provider failure and logs it. It does not throw.

A caller that awaits sendEmail and ignores the return value will report success when no email was sent. If delivery matters to the flow, check the boolean. sendTeamInvitation does this: it logs “mail provider rejected the email” and returns false so the caller can tell the coach.

Template rendering happens before the try, so a rendering error does throw.

Templates

Defined in packages/mail/src/emails/index.ts as mailTemplates. Each is a React component under packages/mail/src/emails/.

`templateId`	Component	Sent when
`magicLink`	`MagicLink`	A user asks for a magic sign-in link.
`forgotPassword`	`ForgotPassword`	Password reset.
`emailVerification`	`EmailVerification`	Verifying an email on signup, and confirming an email change.
`emailOtp`	`EmailOtp`	A one-time code by email.
`organizationInvitation`	`OrganizationInvitation`	A better-auth organization invite.
`teamInvitation`	`TeamInvitation`	A staff member is added from the team screen.
`notification`	`Notification`	The email copy of a coach web notification.

Rendering

getTemplate in packages/mail/src/lib/templates.ts:

Loads the mail translations for the locale with getMessagesForLocale.
Calls the component with the context, the locale and the translations.
Takes the subject from the translations under the template id. For notification, a non-empty context.title replaces it.
Renders HTML and a plain-text version with @react-email/render.

Shared pieces are in packages/mail/src/components (Wrapper, Logo, PrimaryButton). lib/direction.ts handles right-to-left layout for Hebrew, including which way the button arrow points.

Who sends email

Caller	Template	Locale source
`packages/auth/src/auth.ts`, email change confirmation and signup verification	`emailVerification`	The locale cookie on the request (`getLocaleFromRequest`), default locale when absent.
`packages/auth/src/auth.ts`, password reset	`forgotPassword`	Request cookie.
`packages/auth/src/auth.ts`, `magicLink` plugin	`magicLink`	Request cookie.
`packages/auth/src/auth.ts`, `organization` plugin `sendInvitationEmail`	`organizationInvitation`	Request cookie. The link goes to `/login` if the email already has a user, otherwise `/signup`.
`packages/auth/src/auth.ts`, `emailOTP` plugin	`emailOtp`	Request cookie.
`apps/core-api/src/lib/team-invite-mail.ts` `sendTeamInvitation`	`teamInvitation`	The studio’s `locale`, mapped by `toMailLocale`.
`apps/core-api/src/modules/onboarding/onboarding.routes.ts`	`emailOtp`	Fixed to `he`.
`packages/notifications/src/create-notification.ts`	`notification`	The user’s stored `locale`.

Adding a template

Create the component

Add a file under packages/mail/src/emails/. Its props are your context plus locale and translations.

Add it to mailTemplates in packages/mail/src/emails/index.ts. The key becomes the templateId, and TemplateId picks it up automatically.

Add the subject and strings

Add an entry under the same key in the mail translations of every locale in packages/i18n. getTemplate reads subject from there. A missing subject sends an email with an empty subject line.

Rebuild the package

Consumers import the built output of @repo/mail.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Provider

ZeptoMail

Environment variables

`sendEmail`

It never throws

Templates

Rendering

Who sends email

Adding a template

​Provider

​ZeptoMail

​Environment variables

​sendEmail

​It never throws

​Templates

​Rendering

​Who sends email

​Adding a template

Provider

ZeptoMail

Environment variables

`sendEmail`

It never throws

Templates

Rendering

Who sends email

Adding a template