Documentation Index
Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
Use this file to discover all available pages before exploring further.
Spree handles two categories of emails:
| 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 |
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 (or any provider).
Spree Backend → Webhook POST → Storefront → render email → send via Resend
(HMAC signed) (verified) (react-email)
Setup
-
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
-
Configure the storefront with the webhook secret and email provider:
# .env.local (storefront)
SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
RESEND_API_KEY=re_your_resend_api_key
EMAIL_FROM=Your Store <orders@your-domain.com>
- The storefront handles everything else — signature verification, event routing, email rendering, and delivery are built in. See the Next.js storefront email docs 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:
import { verifyWebhookSignature } from '@spree/sdk/webhooks'
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 |
|---|
SMTP_HOST | — | SMTP server address (e.g., smtp.sendgrid.net, smtp.resend.com) |
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., admin@mystore.com) |
RAILS_HOST | example.com | Host used in email URLs |
SMTP_HOST is not set, emails are printed to the Rails log instead of being sent.
Provider Examples
SendGrid
Resend
Postmark
Amazon SES
SMTP_HOST=smtp.sendgrid.net
SMTP_USERNAME=apikey
SMTP_PASSWORD=SG.your-sendgrid-api-key
SMTP_FROM_ADDRESS=admin@mystore.com
SMTP_HOST=smtp.resend.com
SMTP_USERNAME=resend
SMTP_PASSWORD=re_your-resend-api-key
SMTP_FROM_ADDRESS=admin@mystore.com
SMTP_HOST=smtp.postmarkapp.com
SMTP_USERNAME=your-postmark-server-token
SMTP_PASSWORD=your-postmark-server-token
SMTP_FROM_ADDRESS=admin@mystore.com
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_USERNAME=your-ses-access-key-id
SMTP_PASSWORD=your-ses-secret-access-key
SMTP_FROM_ADDRESS=admin@mystore.com
Local Development
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:
To test the full webhook flow locally, use Cloudflare Tunnel:
brew install cloudflared
cloudflared tunnel --url http://localhost:3001
System emails (Rails)
System emails use letter_opener in development — emails open automatically in your browser instead of being sent.
