> ## Documentation Index > Fetch the complete documentation index at: https://docs.bunship.com/llms.txt > Use this file to discover all available pages before exploring further. # Email Templates > Customize transactional emails BunShip uses [React Email](https://react.email) for templating and [Resend](https://resend.com) for delivery. Templates live in the `packages/emails/` package and render to HTML that works across all major email clients. ## Email Package Overview ``` packages/emails/ ├── src/ │ ├── components/ │ │ └── Layout.tsx # Shared header, footer, and styles │ ├── templates/ │ │ ├── welcome.tsx # Post-registration welcome │ │ ├── verify-email.tsx # Email address verification │ │ ├── reset-password.tsx # Password reset link │ │ ├── team-invite.tsx # Organization invitation │ │ ├── invoice.tsx # Payment receipt │ │ └── subscription-canceled.tsx # Cancellation confirmation │ └── index.ts # Public exports ├── package.json └── tsconfig.json ``` Emails are sent through a BullMQ background job queue, so sending never blocks API responses. ## Available Templates BunShip ships with six templates that cover the core SaaS transactional email flows. ### Welcome Email Sent after a user registers. Includes a link to the dashboard. ```typescript theme={null} import { WelcomeEmail } from "@bunship/emails"; ``` ### Verify Email Sent to confirm an email address. Includes a verification link and a resend option. ```typescript theme={null} import { VerifyEmail } from "@bunship/emails"; ``` ### Reset Password Sent when a user requests a password reset. ```typescript theme={null} import { ResetPasswordEmail } from "@bunship/emails"; ``` ### Team Invite Sent when a team member is invited to join an organization. ```typescript theme={null} import { TeamInviteEmail } from "@bunship/emails"; ``` ### Invoice Sent after a successful payment. ```typescript theme={null} import { InvoiceEmail } from "@bunship/emails"; ``` ### Subscription Canceled Sent when a user cancels their subscription. ```typescript theme={null} import { SubscriptionCanceledEmail } from "@bunship/emails"; ``` ## Template Structure Every template follows the same pattern: a props interface, a React component, and inline styles. ```typescript theme={null} // packages/emails/src/templates/welcome.tsx import { Body, Container, Head, Heading, Html, Link, Preview, Text, } from "@react-email/components"; import { appConfig } from "@bunship/config"; interface WelcomeEmailProps { name: string; dashboardUrl: string; } export function WelcomeEmail({ name, dashboardUrl }: WelcomeEmailProps) { return ( Welcome to {appConfig.name} Welcome, {name}! Thanks for signing up. Your account is ready. Go to Dashboard ); } ``` ### The Layout Component All built-in templates use a shared `Layout` component that provides consistent branding, a header with your logo, and a footer with your company details. ```typescript theme={null} import { Layout } from "../components/Layout"; export function MyEmail({ name }: Props) { return ( {/* Your email content goes here */} ); } ``` Edit `packages/emails/src/components/Layout.tsx` to change: * Brand logo URL and dimensions * Header background color * Footer text and links * Default font family ## Creating a Custom Template Add a new file in `packages/emails/src/templates/`: ```typescript theme={null} // packages/emails/src/templates/usage-alert.tsx import { Text, Section, Button } from "@react-email/components"; import { Layout } from "../components/Layout"; import { appConfig } from "@bunship/config"; export interface UsageAlertEmailProps { name: string; resourceName: string; currentUsage: number; limit: number; upgradeUrl: string; } export function UsageAlertEmail({ name, resourceName, currentUsage, limit, upgradeUrl, }: UsageAlertEmailProps) { const percentage = Math.round((currentUsage / limit) * 100); return (

Usage Alert Hi {name}, Your {resourceName} usage has reached{" "} {percentage}% of your plan limit ({currentUsage.toLocaleString()} of{" "} {limit.toLocaleString()}). To avoid service interruptions, consider upgrading your plan. You are receiving this because usage alerts are enabled for your {appConfig.name} account.

); } const heading = { fontSize: "24px", fontWeight: "bold" as const, margin: "0 0 24px", }; const paragraph = { fontSize: "16px", lineHeight: "26px", margin: "0 0 16px", }; const button = { backgroundColor: "#5046e5", borderRadius: "6px", color: "#fff", display: "block" as const, fontSize: "16px", fontWeight: "bold" as const, textAlign: "center" as const, textDecoration: "none", padding: "12px 24px", margin: "24px 0", }; const footer = { fontSize: "14px", color: "#666", marginTop: "32px", }; ``` Add the export to `packages/emails/src/index.ts`: ```typescript theme={null} export { UsageAlertEmail } from "./templates/usage-alert"; export type { UsageAlertEmailProps } from "./templates/usage-alert"; ``` Use the email queue to send asynchronously: ```typescript theme={null} import { renderEmail, UsageAlertEmail } from "@bunship/emails"; const html = await renderEmail( UsageAlertEmail({ name: user.fullName ?? "there", resourceName: "API requests", currentUsage: 8500, limit: 10000, upgradeUrl: `${appConfig.frontendUrl}/billing/upgrade`, }) ); await emailQueue.add("send", { to: user.email, subject: "Usage alert: API requests at 85%", html, }); ``` ## Rendering Emails The `@bunship/emails` package exports two render functions: ### HTML Rendering ```typescript theme={null} import { renderEmail, WelcomeEmail } from "@bunship/emails"; const html = await renderEmail( WelcomeEmail({ name: "John Doe", dashboardUrl: "https://app.yourdomain.com/dashboard", }) ); ``` ### Plain Text Rendering For email clients that do not support HTML: ```typescript theme={null} import { renderEmailText, WelcomeEmail } from "@bunship/emails"; const text = await renderEmailText( WelcomeEmail({ name: "John Doe", dashboardUrl: "https://app.yourdomain.com/dashboard", }) ); ``` ## Sending with Resend BunShip sends emails through Resend via the background job queue. The queue is configured in `featuresConfig.jobs.queues.email`: ```typescript theme={null} // Direct send (not recommended for API routes) import { Resend } from "resend"; const resend = new Resend(process.env.RESEND_API_KEY); await resend.emails.send({ from: `${appConfig.name} `, to: "user@example.com", subject: "Welcome!", html, }); ``` ```typescript theme={null} // Queue-based send (recommended) await emailQueue.add("send", { to: user.email, subject: "Welcome to " + appConfig.name, html, }); ``` Always use the queue for sending emails from API route handlers. This keeps response times fast and handles retries automatically if the email provider is temporarily unavailable. ## Testing Emails Locally React Email includes a development server that renders your templates in the browser with hot reload. ```bash theme={null} cd packages/emails bun run dev ``` This starts a preview server at `http://localhost:3000` where you can: * Browse all templates in a sidebar * Preview with sample data * Toggle between desktop and mobile widths * View the raw HTML output ### Sending Test Emails To send a real test email through Resend (requires a valid API key): ```typescript theme={null} import { renderEmail, WelcomeEmail } from "@bunship/emails"; import { Resend } from "resend"; const resend = new Resend(process.env.RESEND_API_KEY); const html = await renderEmail( WelcomeEmail({ name: "Test User", dashboardUrl: "http://localhost:5173/dashboard", }) ); await resend.emails.send({ from: "test@yourdomain.com", to: "your-email@example.com", subject: "[TEST] Welcome Email", html, }); ``` ## Styling Guidelines Email clients have limited and inconsistent CSS support. Follow these rules for reliable rendering: Email clients strip `