Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Updated docs on new customer facing emails
Damian Legawiec2171bc03c230
diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdxindex 2cfd67c1d0..556daa558c 100644--- a/docs/developer/deployment/emails.mdx+++ b/docs/developer/deployment/emails.mdx@@ -4,11 +4,73 @@ sidebarTitle: Emailsdescription: Learn how to send transactional emails from your Spree application.----Spree sends transactional emails such as order confirmation, password reset, shipping notifications, etc. You can use any SMTP provider — Resend, Postmark, Mailgun, SendGrid, Amazon SES, or your own SMTP server.+Spree handles two categories of emails:-## Configuration+| Category | Sent by | Examples |+|----------|---------|----------|+| **Customer-facing** | Storefront (via webhooks) | Order confirmation, shipping notification, password reset |+| **System/admin** | Spree backend (Rails) | Staff invitation, report ready, export complete |-Set the following environment variables to enable email delivery:+## Customer-Facing Emails (Headless)++In headless builds, customer-facing emails are rendered and sent by the **storefront**, not the backend. The Spree backend publishes webhook events, and the storefront receives them, renders React email templates, and sends via [Resend](https://resend.com) (or any provider).++```+Spree Backend → Webhook POST → Storefront → render email → send via Resend+ (HMAC signed) (verified) (react-email)+```++### Setup++1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks:+ - **URL:** `https://your-storefront.com/api/webhooks/spree`+ - **Events:** `order.completed`, `order.canceled`, `order.shipped`, `customer.password_reset_requested`++2. **Configure the storefront** with the webhook secret and email provider:++```env+# .env.local (storefront)+SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key+RESEND_API_KEY=re_your_resend_api_key+EMAIL_FROM=Your Store <[email protected]>+```++3. **The storefront handles everything else** — signature verification, event routing, email rendering, and delivery are built into `@spree/next/webhooks`. See the [Next.js storefront email docs](/developer/storefront/nextjs/customization#transactional-emails) for template customization.++### Supported Events++| Event | Email |+|-------|-------|+| `order.completed` | Order confirmation with items, totals, addresses |+| `order.canceled` | Cancellation notice |+| `order.shipped` | Shipping notification with tracking link |+| `customer.password_reset_requested` | Password reset link |++### Custom Frameworks++If you're not using the Next.js storefront, you can build your own webhook handler with any framework. Use `@spree/sdk/webhooks` for signature verification:++```typescript+import { verifyWebhookSignature } from '@spree/sdk/webhooks'+```++See [Webhooks documentation](/developer/core-concepts/webhooks) for the full payload format and verification details.++## System Emails (Rails)++System emails are internal notifications sent to **store staff**, not customers. They are sent by the Spree backend via Rails ActionMailer.++| Email | When |+|-------|------|+| Staff invitation | Admin invites a new team member |+| Invitation accepted | Invited user accepts |+| Report ready | Background report generation completes |+| Export complete | Data export finishes |+| Webhook endpoint disabled | Endpoint auto-disabled after repeated failures |++### Configuration++Set the following environment variables on the **Spree backend** to enable system email delivery:| Variable | Default | Description || --- | --- | --- |@@ -16,7 +78,7 @@ Set the following environment variables to enable email delivery:| `SMTP_PORT` | `587` | SMTP server port || `SMTP_USERNAME` | — | SMTP auth username || `SMTP_PASSWORD` | — | SMTP auth password |-| `SMTP_FROM_ADDRESS` | — | Default "from" email address (e.g., `[email protected]`) |+| `SMTP_FROM_ADDRESS` | — | Default "from" email address (e.g., `[email protected]`) || `RAILS_HOST` | `example.com` | Host used in email URLs |When `SMTP_HOST` is not set, emails are printed to the Rails log instead of being sent.@@ -29,7 +91,7 @@ When `SMTP_HOST` is not set, emails are printed to the Rails log instead of beinSMTP_HOST=smtp.sendgrid.netSMTP_USERNAME=apikeySMTP_PASSWORD=SG.your-sendgrid-api-key```<Warning>@@ -42,7 +104,7 @@ When `SMTP_HOST` is not set, emails are printed to the Rails log instead of beinSMTP_HOST=smtp.resend.comSMTP_USERNAME=resendSMTP_PASSWORD=re_your-resend-api-key```</Tab><Tab title="Postmark">@@ -50,7 +112,7 @@ When `SMTP_HOST` is not set, emails are printed to the Rails log instead of beinSMTP_HOST=smtp.postmarkapp.comSMTP_USERNAME=your-postmark-server-tokenSMTP_PASSWORD=your-postmark-server-token```</Tab><Tab title="Amazon SES">@@ -58,22 +120,30 @@ When `SMTP_HOST` is not set, emails are printed to the Rails log instead of beinSMTP_HOST=email-smtp.us-east-1.amazonaws.comSMTP_USERNAME=your-ses-access-key-idSMTP_PASSWORD=your-ses-secret-access-key```</Tab></Tabs>## Local Development-In local development, emails are printed to the Rails log by default. To preview emails with a web UI, run [Mailpit](https://mailpit.axllent.org):+### Customer-facing emails (storefront)++In development, no email provider is needed. Emails are rendered to HTML files in `.next/emails/` with a clickable `file://` link in the console. To preview and design templates:```bash-docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit-SMTP_HOST=localhost bin/dev+npm run email:dev```-Open [http://localhost:8025](http://localhost:8025) to see all outgoing emails.+To test the full webhook flow locally, use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/):++```bash+brew install cloudflared+cloudflared tunnel --url http://localhost:3001+```++Use the tunnel URL as the webhook endpoint URL in Spree Admin.++### System emails (Rails)-<Tip>-If you're using `docker compose up` for development, Mailpit is included automatically and all emails are caught at [http://localhost:8025](http://localhost:8025).-</Tip>+System emails use [letter_opener](https://github.com/ryanb/letter_opener) in development — emails open automatically in your browser instead of being sent.diff --git a/docs/developer/deployment/environment_variables.mdx b/docs/developer/deployment/environment_variables.mdxindex 9ded5abb19..9ca5e3cef4 100644--- a/docs/developer/deployment/environment_variables.mdx+++ b/docs/developer/deployment/environment_variables.mdx@@ -17,6 +17,10 @@ These variables are required to run Spree in production.## Email (SMTP)+<Tip>+This configuration is used for system emails (e.g. staff invitations, report ready, export complete). Customer facing emails are handled by the [storefront via webhooks](/developer/storefront/nextjs/customization#transactional-emails).+</Tip>+Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, emails are logged to stdout.| Variable | Default | Description |diff --git a/docs/developer/storefront/nextjs/customization.mdx b/docs/developer/storefront/nextjs/customization.mdxindex 0d932abddd..fe8ea10d1a 100644--- a/docs/developer/storefront/nextjs/customization.mdx+++ b/docs/developer/storefront/nextjs/customization.mdx@@ -136,6 +136,66 @@ export default async function YourNewPage() {}```+## Transactional Emails++Customer-facing emails are rendered in the storefront using [react-email](https://react.email) and sent via [Resend](https://resend.com). The Spree backend delivers order/shipment/password events to the storefront via [webhooks](/developer/core-concepts/webhooks).++### Templates++Email templates are React components in `src/lib/emails/`:++| File | Event | Description |+|------|-------|-------------|+| `order-confirmation.tsx` | `order.completed` | Items, totals, addresses, delivery method |+| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |+| `shipment-shipped.tsx` | `order.shipped` | Tracking number and link |+| `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |++Customize templates by editing these files directly. They use `@react-email/components` for email-safe layout primitives.++### Previewing++```bash+npm run email:dev+```++Opens the react-email dev server with mock data for all templates at `http://localhost:3000`.++### Webhook Handler++The webhook route (`src/app/api/webhooks/spree/route.ts`) uses `createWebhookHandler` from `@spree/next/webhooks`:++```typescript+import { createWebhookHandler } from '@spree/next/webhooks'++export const POST = createWebhookHandler({+ secret: process.env.SPREE_WEBHOOK_SECRET!,+ handlers: {+ 'order.completed': handleOrderCompleted,+ 'order.canceled': handleOrderCanceled,+ 'order.shipped': handleOrderShipped,+ 'customer.password_reset_requested': handlePasswordReset,+ },+})+```++To add a new email type:++1. Create a template in `src/lib/emails/`+2. Add a handler function in `src/lib/webhooks/handlers.ts`+3. Register the event in `route.ts`+4. Subscribe to the event in Spree Admin → Webhooks++### Local Development++In dev, emails are written to `.next/emails/` as HTML files — no Resend key needed. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) to receive webhooks locally:++```bash+cloudflared tunnel --url http://localhost:3001+```++For full setup details, see [Sending out Emails](/developer/deployment/emails).+## Building a Custom StorefrontIf you prefer to build from scratch instead of forking the starter, you can use the `@spree/next` and `@spree/sdk` packages directly in any Next.js application. See the [@spree/next Package](/developer/storefront/nextjs/spree-next-package) documentation for the complete API reference.