Sending out Emails

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

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, newsletter_subscriber.subscription_requested

2. Configure the storefront with the webhook secret and email provider:

   envCopy

   # .env.local (storefront)
   SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
   RESEND_API_KEY=re_your_resend_api_key
   EMAIL_FROM=Your Store <[email protected]>
   

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:

import { verifyWebhookSignature } from '@spree/sdk/webhooks'

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

<Warning>
Remember to verify the email address in SendGrid you intend to use for sending, otherwise emails will be rejected.
[Read more about sender verification](https://www.twilio.com/docs/sendgrid/ui/sending-email/sender-verification).
</Warning>

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:

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.

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.