Email

Email Package (`@repo/email`)

This package provides a simple, standardized way to send transactional emails using Resend.

Why You Need This

Centralized email sending keeps your messages consistent and ensures templates match your brand. It also abstracts the provider API, so switching services is painless. Check Getting Started to configure credentials.

Features

Abstracts email sending logic behind a simple EmailService.
Uses Resend for reliable email delivery.
Supports both HTML and plain text emails.
Includes pre-built, type-safe React email templates.
Configured via environment variables.

Setup

Resend Account: Sign up for a Resend account and obtain an API key.
Domain Verification: Verify your sending domain with Resend.
Environment Variable: Add your Resend API key to your environment variables (e.g., in .env):
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxx

Core Component: `EmailService`

The primary interface for sending emails is the EmailService class found in src/index.server.ts.

Initialization

Create an instance of the service, typically once during application startup.

import { EmailService } from "@repo/email";

const emailService = EmailService.create({
  defaultFrom: "Your Name <noreply@yourverifieddomain.com>", // Must be a verified sender in Resend
});

Info: The RESEND_API_KEY environment variable is read automatically during initialization.

Sending Emails

The service provides methods for sending both plain text and HTML emails.

// Send a simple text email
emailService.sendEmail(
  "recipient@example.com",
  "Subject Line",
  "This is the plain text content."
);

// Send an HTML email (automatically generates text version from HTML)
emailService.sendHtmlEmail(
  "recipient@example.com",
  "Subject Line",
  "<h1>Hello World</h1><p>This is HTML content.</p>"
);

// Send HTML email with a specific text version
emailService.sendHtmlEmail(
  "recipient@example.com",
  "Subject Line",
  "<h1>HTML Content</h1>",
  { text: "Explicit Text Version" }
);

Email Templates

The package includes pre-built React email templates located in src/templates/. These templates ensure consistent branding and structure for common transactional emails.

Available Templates

(List might evolve, check src/templates/index.ts for current exports)

VerificationEmail: For verifying a user's email address.
PasswordResetEmail: For the password reset flow.
WelcomeEmail: Sent to new users upon registration.
OrganizationInvitationEmail: For inviting users to join an organization.
TeamInvitationEmail: For inviting users to join a specific team within an organization.

Using Templates

Import the required template component.
Use render from @react-email/render to generate the HTML and text versions.
Pass the rendered content to emailService.sendHtmlEmail.

import { EmailService } from "@repo/email";
import { WelcomeEmail } from "@repo/email/templates";
import { render } from "@react-email/render";

const emailService = EmailService.create({ /* ... */ });

const userEmail = "newuser@example.com";
const userName = "Jane Doe";
const loginUrl = "https://yourapp.com/login";

// Render the React component to HTML
const emailHtml = render(<WelcomeEmail name={userName} loginUrl={loginUrl} />);
// Render the React component to plain text
const emailText = render(<WelcomeEmail name={userName} loginUrl={loginUrl} />, { plainText: true });

// Send the email using the rendered template
emailService.sendHtmlEmail(
  userEmail,
  "Welcome to Our App!", // Subject line
  emailHtml,
  { text: emailText }
);

Note: Always provide both HTML and text versions for better email client compatibility and deliverability.

Integration

This package is typically used by other backend packages or services that need to trigger email sending, such as:

@repo/auth: For sending verification, password reset, and invitation emails.
@repo/api: For sending notifications or other application-specific emails.