Skip to main content
Spree handles two categories of emails:

​
Customer-Facing Emails

By default, Spree sends all customer transactional emails itself — the spree_emails gem ships installed in every deployment. This works for every client of the API: mobile apps, custom frontends, POS integrations — no storefront required. Delivery uses the same SMTP configuration as system emails. Customer emails can be turned off in the admin under Settings → Emails — do this when your storefront takes over sending them (below), otherwise customers receive both.

​
Sending from the Storefront Instead

With the Next.js storefront, you can let the storefront own the customer email experience: the Spree backend publishes webhook events, and the storefront receives them, renders React email templates, and sends via Resend (or any provider).

​
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, newsletter_subscriber.subscription_requested
  2. Configure the storefront with the webhook secret and email provider:
  3. 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.
  4. Turn off Spree’s own customer emails under Settings → Emails in the admin, so customers don’t receive duplicates.

​
Supported Events

​
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:
See Webhooks documentation for the full payload format and verification details.

​
System Emails

System emails are internal notifications sent to store staff, not customers. They are always sent by Spree itself and can’t be taken over by a storefront.

​
Configuration

Set the following environment variables on the Spree backend to enable email delivery — this configuration powers both customer transactional emails and system emails: When SMTP_HOST is not set, emails are printed to the Rails log instead of being sent.

​
Provider Examples

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

​
Storefront-sent emails

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:
Use the tunnel URL as the webhook endpoint URL in Spree Admin.

​
Spree-sent emails

In development, all emails Spree sends (customer and system alike) are captured by Mailpit — nothing is delivered externally. Open http://localhost:8025 to read them. To deliver through a real provider instead, set SMTP_HOST (and friends) in .env.