ContextQMD
Back to Spree

Spree Emails

spree/emails/README.md

5.6.05.4 KB
Original Source

Spree Emails

Spree Emails provides transactional email templates and mailers for Spree Commerce, handling order confirmations, shipment notifications, and other customer communications.

Overview

This gem includes:

  • Order Mailer - Order confirmation and cancellation emails
  • Shipment Mailer - Shipping and delivery notifications
  • Reimbursement Mailer - Refund notifications
  • Event Subscribers - Automatic email triggers on store events
  • Email Templates - Customizable HTML and text templates

Installation

bash
bundle add spree_emails

Email Types

Order Emails

  • Order Confirmation - Sent when an order is completed
  • Order Cancellation - Sent when an order is cancelled

Shipment Emails

  • Shipment Notification - Sent when a shipment is shipped
  • Delivery Confirmation - Sent when tracking shows delivered

Reimbursement Emails

  • Refund Notification - Sent when a reimbursement is processed

Configuration

Transactional emails are controlled per-store via the send_consumer_transactional_emails preference. This can be configured in the admin dashboard under Store Settings, or programmatically:

ruby
# Enable/disable transactional emails for a store
store = Spree::Store.current
store.update(send_consumer_transactional_emails: true)

The sender address is configured via the mail_from_address attribute on each store:

ruby
store.update(mail_from_address: '[email protected]')

Action Mailer Configuration

ruby
# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: 'smtp.example.com',
  port: 587,
  user_name: ENV['SMTP_USERNAME'],
  password: ENV['SMTP_PASSWORD'],
  authentication: 'plain',
  enable_starttls_auto: true
}

Customization

Overriding Templates

Copy email templates to your application:

bash
# Copy all email templates
cp -r $(bundle show spree_emails)/app/views/spree/mailer app/views/spree/

# Or copy specific templates
cp $(bundle show spree_emails)/app/views/spree/mailer/order_mailer/confirm_email.html.erb \
   app/views/spree/mailer/order_mailer/

Template Structure

app/views/spree/mailer/
├── order_mailer/
│   ├── confirm_email.html.erb
│   ├── confirm_email.text.erb
│   ├── cancel_email.html.erb
│   └── cancel_email.text.erb
├── shipment_mailer/
│   ├── shipped_email.html.erb
│   └── shipped_email.text.erb
└── reimbursement_mailer/
    ├── reimbursement_email.html.erb
    └── reimbursement_email.text.erb

Custom Mailer

Create custom mailers by extending Spree's base mailer:

ruby
# app/mailers/spree/order_mailer_decorator.rb
module Spree
  module OrderMailerDecorator
    def confirm_email(order, resend = false)
      @custom_data = fetch_custom_data(order)
      super
    end

    private

    def fetch_custom_data(order)
      # Custom logic
    end
  end
end

Spree::OrderMailer.prepend(Spree::OrderMailerDecorator)

Adding New Email Types

ruby
# app/mailers/spree/custom_mailer.rb
module Spree
  class CustomMailer < BaseMailer
    def welcome_email(user)
      @user = user
      mail(to: @user.email, subject: 'Welcome to our store!')
    end
  end
end

Event Integration

Emails are triggered via Spree's event system. Create custom subscribers:

ruby
# app/subscribers/my_app/custom_email_subscriber.rb
module MyApp
  class CustomEmailSubscriber < Spree::Subscriber
    subscribes_to 'customer.created'

    def handle(event)
      user_id = event.payload['id']
      user = Spree.user_class.find_by(id: user_id)
      return unless user

      Spree::CustomMailer.welcome_email(user).deliver_later
    end
  end
end

Then register the subscriber in an initializer:

ruby
# config/initializers/spree.rb
Rails.application.config.after_initialize do
  Spree.subscribers << MyApp::CustomEmailSubscriber
end

Disabling Emails

Disable transactional emails for a specific store:

ruby
store = Spree::Store.current
store.update(send_consumer_transactional_emails: false)

This setting can also be managed in the admin dashboard under Store Settings.

To disable all Spree transactional emails globally, remove this gem from your application:

bash
bundle remove spree_emails

Using Third-Party Email Services

If you prefer to use a third-party email service like Klaviyo for transactional emails, you can use the spree_klaviyo extension. This allows you to leverage Klaviyo's email marketing platform for order confirmations, shipment notifications, and other transactional emails.

Previewing emails

ActionMailer previews for every transactional email ship with this gem and are served automatically in development — no setup required. With a seeded development database, start the server and visit:

http://localhost:3000/rails/mailers

for example http://localhost:3000/rails/mailers/spree/order/confirm_email.

Testing

Run the test suite:

bash
cd emails
bundle exec rake test_app  # First time only
bundle exec rspec

Documentation