Skip to main content
Spree handles two categories of emails:
CategorySent byExamples
Customer-facingStorefront (via webhooks)Order confirmation, shipping notification, password reset
System/adminSpree 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

  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.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>
  1. 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

EventEmail
order.completedOrder confirmation with items, totals, addresses
order.canceledCancellation notice
order.shippedShipping notification with tracking link
customer.password_reset_requestedPassword 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'
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.
EmailWhen
Staff invitationAdmin invites a new team member
Invitation acceptedInvited user accepts
Report readyBackground report generation completes
Export completeData export finishes
Webhook endpoint disabledEndpoint auto-disabled after repeated failures

​
Configuration

Set the following environment variables on the Spree backend to enable system email delivery:
VariableDefaultDescription
SMTP_HOST—SMTP server address (e.g., smtp.sendgrid.net, smtp.resend.com)
SMTP_PORT587SMTP 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_HOSTexample.comHost used in email URLs
When SMTP_HOST is not set, emails are printed to the Rails log instead of being sent.

​
Provider Examples

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.

​
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.