Sending out Emails

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, newsletter_subscriber.subscription_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
`newsletter_subscriber.subscription_requested`	Newsletter double opt-in confirmation 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'

See Webhooks documentation 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
`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`	Public host used in email links and other generated URLs — image/attachment URLs use `CDN_HOST` instead when set

When 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

Remember to verify the email address in SendGrid you intend to use for sending, otherwise emails will be rejected. Read more about sender verification.

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:

npm run email:dev

To test the full webhook flow locally, use Cloudflare Tunnel:

brew install cloudflared
cloudflared tunnel --url http://localhost:3001

Use the tunnel URL as the webhook endpoint URL in Spree Admin.

System emails (Rails)

System emails use letter_opener in development — emails open automatically in your browser instead of being sent.

Deployment

Upgrading

Contributing

Security

Customer-Facing Emails (Headless)

Setup

Supported Events

Custom Frameworks

System Emails (Rails)

Configuration

Provider Examples

Local Development

Customer-facing emails (storefront)

System emails (Rails)

​Customer-Facing Emails (Headless)

​Setup

​Supported Events

​Custom Frameworks

​System Emails (Rails)

​Configuration

​Provider Examples

​Local Development

​Customer-facing emails (storefront)

​System emails (Rails)

Customer-Facing Emails (Headless)

Setup

Supported Events

Custom Frameworks

System Emails (Rails)

Configuration

Provider Examples

Local Development

Customer-facing emails (storefront)

System emails (Rails)