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.

4.0 KB
Raw Blame
---
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).