Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Updated docs on new customer facing emails

Damian Legawiec2171bc03c230
diff --git a/docs/developer/deployment/emails.mdx b/docs/developer/deployment/emails.mdx
index 2cfd67c1d0..556daa558c 100644
--- a/docs/developer/deployment/emails.mdx
+++ b/docs/developer/deployment/emails.mdx
@@ -4,11 +4,73 @@ sidebarTitle: Emails
description: 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 bein
SMTP_HOST=smtp.sendgrid.net
SMTP_USERNAME=apikey
SMTP_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 bein
SMTP_HOST=smtp.resend.com
SMTP_USERNAME=resend
SMTP_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 bein
SMTP_HOST=smtp.postmarkapp.com
SMTP_USERNAME=your-postmark-server-token
SMTP_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 bein
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_USERNAME=your-ses-access-key-id
SMTP_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.mdx
index 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.mdx
index 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 Storefront
If 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.