Email Notification Endpoints

The boilerplate ships two public API routes that send transactional email through Resend. Both are optional — email is env-gated by RESEND_API_KEY. When that variable is unset, the endpoints do nothing and respond with { skipped: true }, so a store running in the default quote-based mode keeps working without any email provider configured.

• POST /api/quotes/notify — fires when a customer submits a quote request. Sends an admin alert plus a customer confirmation.
• POST /api/notifications/status — fires when an admin changes a quote or order status. Sends a status-change email to the customer.

Shared behavior

Both routes live in src/app/api/quotes/notify/route.ts and src/app/api/notifications/status/route.ts and share the same contract, defined by the zod schemas in src/lib/email.ts:

• Public, no auth. Anyone can POST. Because of that, request bodies are strictly zod-validated and size-capped (string/array length limits on every field).
• Identifier + fallback trust model. Each request carries an identifier (quoteNumber, or kind + referenceNumber) plus an optional fallback block with the full email content. When the server has Firebase Admin credentials (FIREBASE_SERVICE_ACCOUNT*), it looks the record up in Firestore by the identifier and rebuilds the recipient and content from the persisted document — the fallback block is ignored, and an unknown identifier returns 404 without sending mail. Without admin credentials (credential-free starter mode), the route renders the validated fallback block instead; a request without one is rejected with 400. See SECURITY.md in the repo root for the threat model.
• Never echo input. Error responses are generic ("Invalid request body", "Invalid JSON body") and never reflect the submitted data back.
• Email is optional. The RESEND_API_KEY is read inside the handler and the Resend client is instantiated lazily, so builds and deployments without the key succeed. When the key is missing the route returns 200 with { skipped: true, reason: "email not configured" }.
• Rate limited per client IP (in-memory), returning 429 with a Retry-After header when exceeded.

Rate limits

The client IP is derived by clientIpFrom(request) from src/lib/rate-limit.ts. When the limit is hit:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{ "error": "Too many requests" }

Response codes

POST /api/quotes/notify

Sends two emails via resend.emails.send, dispatched together with Promise.allSettled:

1. Admin alert — to is QUOTE_NOTIFICATION_EMAIL, falling back to siteConfig.contact.email. Subject: New quote request <quoteNumber>.
2. Customer confirmation — to is customer.email. Subject: We received your quote request <quoteNumber>.

Both use QuoteEmailTemplate (rendered with audience: "admin" and audience: "customer" respectively). The from address is RESEND_FROM_EMAIL, defaulting to onboarding@resend.dev.

The response reports how many of the two sends succeeded:

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

Request body — quoteNotifyRequestSchema

With admin credentials configured, { "quoteNumber": "Q-…" } alone is a complete request — everything else is read from the persisted quote. The storefront always includes fallback so credential-free deployments keep working.

fallback

customer

items[]

discount (the code applied in the cart, with the amount taken off)

Example request

curl -X POST https://your-store.example/api/quotes/notify \
  -H "Content-Type: application/json" \
  -d '{
    "quoteNumber": "Q-20260703-0042",
    "fallback": {
      "customer": {
        "firstName": "Dana",
        "lastName": "Reyes",
        "email": "dana@acme.test",
        "companyName": "Acme Industrial"
      },
      "items": [
        {
          "id": "prod_123",
          "productName": "Stainless Bolt M8",
          "brand": "FastenPro",
          "variantName": "50mm",
          "quantity": 500,
          "price": 0.12
        }
      ],
      "message": "Please quote bulk pricing for a recurring monthly order.",
      "discount": { "code": "WELCOME10", "amount": 6.00 }
    }
  }'

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

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

POST /api/notifications/status

Sends one email to the customer notifying them that their quote or order status changed. Uses StatusUpdateEmailTemplate. Subject: Update on your <kind> <referenceNumber>: <status>. The from address is RESEND_FROM_EMAIL (default onboarding@resend.dev).

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

Request body — statusUpdateRequestSchema

With admin credentials configured the recipient, current status, item count, and total all come from the persisted record; fallback is ignored.

fallback

customer

Example request

curl -X POST https://your-store.example/api/notifications/status \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "quote",
    "referenceNumber": "Q-20260703-0042",
    "fallback": {
      "status": "approved",
      "customer": {
        "email": "dana@acme.test",
        "firstName": "Dana",
        "lastName": "Reyes"
      },
      "itemCount": 3,
      "total": 148.50
    }
  }'

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

Client helper: sendStatusUpdateNotification

src/lib/email.ts exports a fire-and-forget helper used by admin status-update code so you rarely POST this endpoint by hand:

import { sendStatusUpdateNotification } from "@/lib/email";

sendStatusUpdateNotification({
  kind: "order",
  referenceNumber: order.number,
  status: "shipped",
  customer: order.customer, // loose shape; email is validated
  itemCount: order.items.length,
  total: order.total,
});

It builds a statusUpdateRequestSchema-shaped payload — the kind + referenceNumber identifier plus a fallback content block — and POSTs it in the background. It never throws and never blocks the caller, and silently does nothing when the customer record has no valid-looking email — email is a best-effort side effect of a status update. It trims and truncates names, clamps referenceNumber/status to their max lengths, and only includes itemCount/total when they pass the same bounds the schema enforces. Servers with Firebase Admin credentials ignore the fallback block and rebuild the email from the persisted record.

Environment variables

See environment variables for the full list and the emails feature guide for setup steps and template details.