> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sending out Emails

> Learn how to send transactional emails from your Spree application.

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](https://resend.com) (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 theme={"theme":"night-owl"}
# .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>
```

3. **The storefront handles everything else** — signature verification, event routing, email rendering, and delivery are built in. See the [Next.js storefront email docs](/developer/storefront/nextjs/customization#transactional-emails) 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 theme={"theme":"night-owl"}
import { verifyWebhookSignature } from '@spree/sdk/webhooks'
```

See [Webhooks documentation](/developer/core-concepts/webhooks) 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` | 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 theme={"theme":"night-owl"}
    SMTP_HOST=smtp.sendgrid.net
    SMTP_USERNAME=apikey
    SMTP_PASSWORD=SG.your-sendgrid-api-key
    SMTP_FROM_ADDRESS=admin@mystore.com
    ```

    <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 theme={"theme":"night-owl"}
    SMTP_HOST=smtp.resend.com
    SMTP_USERNAME=resend
    SMTP_PASSWORD=re_your-resend-api-key
    SMTP_FROM_ADDRESS=admin@mystore.com
    ```
  </Tab>

  <Tab title="Postmark">
    ```bash theme={"theme":"night-owl"}
    SMTP_HOST=smtp.postmarkapp.com
    SMTP_USERNAME=your-postmark-server-token
    SMTP_PASSWORD=your-postmark-server-token
    SMTP_FROM_ADDRESS=admin@mystore.com
    ```
  </Tab>

  <Tab title="Amazon SES">
    ```bash theme={"theme":"night-owl"}
    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
    ```
  </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 theme={"theme":"night-owl"}
npm run email:dev
```

To test the full webhook flow locally, use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/):

```bash theme={"theme":"night-owl"}
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](https://github.com/ryanb/letter_opener) in development — emails open automatically in your browser instead of being sent.