Sending out Emails - Spree

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

# .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]>

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:

typescript

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., `[email protected]`)
`RAILS_HOST`	`example.com`	Host used in email URLs

When SMTP_HOST is not set, emails are printed to the Rails log instead of being sent.

Provider Examples

<Tabs> <Tab title="SendGrid"> ```bash SMTP_HOST=smtp.sendgrid.net SMTP_USERNAME=apikey SMTP_PASSWORD=SG.your-sendgrid-api-key [email protected] ```

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

</Tab> <Tab title="Resend"> ```bash SMTP_HOST=smtp.resend.com SMTP_USERNAME=resend SMTP_PASSWORD=re_your-resend-api-key [email protected] ``` </Tab> <Tab title="Postmark"> ```bash SMTP_HOST=smtp.postmarkapp.com SMTP_USERNAME=your-postmark-server-token SMTP_PASSWORD=your-postmark-server-token [email protected] ``` </Tab> <Tab title="Amazon SES"> ```bash SMTP_HOST=email-smtp.us-east-1.amazonaws.com SMTP_USERNAME=your-ses-access-key-id SMTP_PASSWORD=your-ses-secret-access-key [email protected] ``` </Tab> </Tabs>

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:

bash

npm run email:dev

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

bash

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.