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
---
title: Transactional Emails
description: Render and send order, shipment, and account emails from the Spree Next.js Storefront with react-email, Resend, and Spree webhooks
---
The storefront can own its customer-facing transactional emails instead of the Spree backend. Emails are rendered with [react-email](https://react.email) and sent via [Resend](https://resend.com); the Spree backend delivers order, shipment, and account events to the storefront over [webhooks](/developer/core-concepts/webhooks).
```
Spree Backend → Webhook POST → /api/webhooks/spree → render email → send via Resend
(signed HMAC) (signature verified) (react-email) (or write to disk in dev)
```
## Templates
Email templates are React components in `src/lib/emails/`:
| File | Event | Description |
|------|-------|-------------|
| `order-confirmation.tsx` | `order.placed` | Items, totals, addresses, delivery method |
| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |
| `shipment-shipped.tsx` | `order.fulfilled` | Tracking number and link |
| `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |
| `data-request-confirmation.tsx` | `data_request.confirmation_requested` | Link that confirms a customer's data request |
Customize a template by editing its file directly — they use `@react-email/components` for email-safe layout primitives.
<Note>
Spree 6.0 also sends the pre-6.0 names `order.completed` and `order.shipped` as deprecated aliases until 6.1. Subscribe the endpoint to the new names only — subscribing to both makes Spree deliver both events.
</Note>
## Previewing
Run the storefront in development and open [http://localhost:3001/dev/emails](http://localhost:3001/dev/emails):
```bash
pnpm dev
```
Each template renders with sample data via `@react-email/render`. The route is gated to non-production environments.
## Configuration
Add these to `.env.local`:
```env
SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
RESEND_API_KEY=re_your_resend_api_key # production only
EMAIL_FROM=Your Store <[email protected]> # production only
```
In development no `RESEND_API_KEY` is needed — emails are written to `.next/emails/` as HTML files with a `file://` link logged to the console.
## Webhook Handler
The webhook route (`src/app/api/webhooks/spree/route.ts`) wires events to handlers with `createWebhookHandler` from `src/lib/spree/webhooks`. Signature verification and event routing are handled for you:
```typescript
import { createWebhookHandler } from '@/lib/spree/webhooks'
const handler = createWebhookHandler({
secret: process.env.SPREE_WEBHOOK_SECRET!,
handlers: {
'order.placed': handleOrderPlaced,
'order.canceled': handleOrderCanceled,
'order.fulfilled': handleOrderFulfilled,
'customer.password_reset_requested': handlePasswordReset,
'data_request.confirmation_requested': handleDataRequestConfirmation,
},
})
```
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 → Settings → Developer → Webhooks**.
## Setup
1. **Create a webhook endpoint** in Spree Admin → Settings → Developer → Webhooks. Subscribe to `order.placed`, `order.canceled`, `order.fulfilled`, `customer.password_reset_requested` and `data_request.confirmation_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
2. **Receive webhooks locally.** Expose the storefront with a public URL so Spree can reach it — the simplest option is a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
```bash
brew install cloudflared
cloudflared tunnel --url http://localhost:3001
```
Use the tunnel URL as the webhook endpoint URL in Spree Admin.
For the backend perspective on delivering these events, see [Sending out Emails](/developer/deployment/emails).