Transactional Emails

The boilerplate can send two kinds of transactional email through Resend: a pair of quote-request notifications (an admin alert plus a customer confirmation) when a shopper submits a cart as a quote, and a status-change email when an admin moves a quote or order to a new status. Both are rendered with react-email templates.

How it fits together

There are two server routes, each backed by a react-email template:

Both routes are public, so they are rate-limited, validate their body strictly against a zod schema, and never echo request data back in error responses. The Resend client is instantiated lazily inside the handler (only after the key check passes) so builds and deployments without the env var succeed.

The client-side callers are fire-and-forget: the cart posts to /api/quotes/notify and ignores the outcome, and the admin pages call a helper that posts to /api/notifications/status in the background. Email delivery never blocks the underlying commerce action.

For the request/response contracts of these endpoints, see the notifications API reference.

Configuration

All configuration is via environment variables. See environment variables for the full list.

# Optional: quote notification emails via Resend (server-side only).
# Leave RESEND_API_KEY empty to disable emails entirely.
RESEND_API_KEY=
# Verified sender ("onboarding@resend.dev" works for testing).
RESEND_FROM_EMAIL=
# Inbox that receives new-quote notifications (defaults to the site contact email).
QUOTE_NOTIFICATION_EMAIL=

Enabling email

RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL="Acme Store <quotes@yourdomain.com>"
QUOTE_NOTIFICATION_EMAIL=sales@yourdomain.com

Quote notifications — POST /api/quotes/notify

When a shopper submits their cart as a quote, Cart.tsx posts the quote payload to this endpoint. On success the route sends two emails via Promise.allSettled, both rendered from the same QuoteEmailTemplate component with a different audience prop:

• Admin alert → QUOTE_NOTIFICATION_EMAIL (falls back to siteConfig.contact.email), subject New quote request <quoteNumber>. Rendered with audience: "admin" — includes the full customer contact block (name, company, email, phone).
• Customer confirmation → customer.email, subject We received your quote request <quoteNumber>. Rendered with audience: "customer" — a friendly summary of what they requested.

Request body

Validated against quoteNotifyRequestSchema in src/lib/email.ts. Sizes are capped because the endpoint is public. The body is an identifier plus an optional fallback content block: when the server has Firebase Admin credentials it looks the quote up in Firestore by quoteNumber and builds both emails from the persisted record (fallback is ignored; unknown numbers get a 404); without admin credentials it renders the validated fallback block instead. See SECURITY.md for the trust model.

Prices are optional throughout: quote-based catalogs may not carry prices, and the template renders an em dash where a price is absent.

Example request

curl -X POST http://localhost:3000/api/quotes/notify \
  -H "Content-Type: application/json" \
  -d '{
    "quoteNumber": "Q-1042",
    "fallback": {
      "customer": {
        "firstName": "Dana",
        "lastName": "Reed",
        "email": "dana@example.com",
        "companyName": "Reed Interiors"
      },
      "items": [
        { "productName": "Studio Monitor", "brand": "Acme", "quantity": 2, "price": 199 }
      ],
      "message": "Do you offer bulk pricing?",
      "discount": { "code": "WELCOME10", "amount": 39.8 }
    }
  }'

Responses

{ "sent": 2, "failed": 0 }

{ "skipped": true, "reason": "email not configured" }

sent and failed count the two messages independently — a partial failure (for example, the admin address bounces) still returns 200 with { "sent": 1, "failed": 1 }. Resend resolves with { data, error } rather than throwing, so an error on the resolved value is counted as a failure.

Status-change notifications — POST /api/notifications/status

When an admin updates a quote or order status (in admin/quotes or admin/orders), the page calls the sendStatusUpdateNotification helper from src/lib/email.ts. The helper is best-effort: it trims and plausibility-checks the customer email, silently does nothing when there is no valid-looking address, never throws, and never blocks the admin action. It then posts to this endpoint, which sends a single email rendered from StatusUpdateEmailTemplate.

The email copy adapts to kind and status. Recognised statuses get tailored subject and body copy; anything else falls back to a generic "status changed" message.

The subject line is Update on your <kind> <referenceNumber>: <status>, and the email links the customer to ${siteConfig.url}/account?tab=quotes or ?tab=orders depending on kind.

Request body

Validated against statusUpdateRequestSchema in src/lib/email.ts. Like the quote endpoint, the body is an identifier plus an optional fallback block: servers with Firebase Admin credentials look the quote/order up by kind + referenceNumber and build the email from the persisted record (recipient, current status, item count, total), ignoring fallback; credential-free servers render the validated fallback block.

Example request

curl -X POST http://localhost:3000/api/notifications/status \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "quote",
    "referenceNumber": "Q-1042",
    "fallback": {
      "status": "Quoted",
      "customer": { "email": "dana@example.com", "firstName": "Dana" },
      "itemCount": 2
    }
  }'

Responses

{ "sent": 1, "failed": 0 }

{ "skipped": true, "reason": "email not configured" }

A delivery failure returns 200 with { "sent": 0, "failed": 1 } rather than an error, since the email is a side effect of an already-successful status update.

Rate limiting

Both routes use the in-process fixed-window limiter from src/lib/rate-limit.ts, keyed by client IP. When the limit is exceeded they return 429 with a Retry-After header (in seconds).

The email templates

Both templates live in src/components/emailing and are built with react-email components (Html, Head, Body, Container, Tailwind, Text, Hr, Preview, and Link) styled with the react-email Tailwind wrapper. They pull the store name from siteConfig.name and format money with the shared formatMoney helper (rendering an em dash when a value is absent).

• QuoteEmailTemplate takes an audience prop of "admin" or "customer". The admin variant shows the full customer contact block and an internal call to action; the customer variant is a friendly confirmation. Both render a requested-products table (product, quantity, price, subtotal) and an optional discount line and notes section.
• StatusUpdateEmailTemplate renders the adaptive heading/body from the status map, a reference/status summary with optional item count and total, and an "View in your account" link.

To preview or customise these, edit the .tsx files directly — they are plain React components. Changing copy, colours, or layout does not require touching the API routes.

Related