emails

Purpose

packages/emails holds the transactional email templates for Cal.diy. Booking confirmations, reschedule notices, cancellation notices, daily digests, payment receipts, password reset emails, magic-link emails, and team invitations all live here.

Directory layout

The package is rendered from React components (the project uses React Email–style JSX templates that compile to HTML + plain text).

packages/emails/
├── src/
│   ├── components/        # Shared layout primitives (header, footer, button)
│   ├── templates/         # One file per template
│   ├── i18n/              # i18n hooks for emails
│   ├── lib/               # Helpers (BOOKER_URL, calendar attachment builder, ...)
│   └── ...
├── package.json
└── tsconfig.json

Sending pipeline

Email sending in Cal.diy is split:

1. Render — a service composes a React template (e.g., AttendeeScheduledEmail) and renders it to HTML + plain text.
2. Send — packages/lib/Sendgrid.ts (and SMTP fallback) actually transmits. The provider is selected by env vars (EMAIL_FROM, EMAIL_SERVER_*, or SendGrid API key).
3. Defer — for non-urgent mail, the booking pipeline enqueues a tasker job (packages/features/tasker) instead of sending inline.
4. Reminder cadence — the GitHub Actions cron cron-bookingReminder.yml, cron-scheduleEmailReminders.yml, cron-monthlyDigestEmail.yml poke endpoints that drain queued reminders.

Conventions

• Templates pull copy through packages/i18n/locales/<locale>/common.json so users see localized emails. The default locale is en.
• Reply-to behavior is centralized in packages/lib/getReplyToEmail.ts and packages/lib/getReplyToHeader.ts — these handle the case where attendees should reply to the organizer instead of the no-reply mailbox.
• Test-only deliveries go through packages/lib/testEmails.ts (uses mailhog in CI; configured in vitest-mocks/).

Integration points

• Booking pipeline — every transition emits at least one email. See packages/features/bookings/lib/handleNewBooking/, handleConfirmation/, handleCancelBooking/.
• Workflows / reminders — even with the EE workflow runtime being deprecated, basic reminders still flow through tasker → email.
• NextAuth — magic-link / verification / password-reset emails are sent here.

Entry points for modification

• Add a template: drop a new file under packages/emails/src/templates/, expose a render function, hook it into the relevant booking step or trigger.
• Change brand: edit the shared components (header, footer, colors) under packages/emails/src/components/.
• Localize: add the new key to packages/i18n/locales/en/common.json (and ideally other locales) and reference it from the template.

Related pages

• features → bookings — the largest emitter
• tooling — Sendgrid + SMTP wiring