Rails Mailers

Email with ActionMailer

Send transactional and notification emails using ActionMailer, integrated with SolidQueue for async delivery. Create HTML and text templates, preview emails in development, and test thoroughly.

• Sending transactional emails (password resets, confirmations, receipts)
• Sending notification emails (updates, alerts, digests)
• Delivering emails asynchronously via background jobs
• Creating email templates with HTML and text versions
• Testing email delivery and content

• Async Delivery - ActionMailer integrates with SolidQueue for non-blocking email sending
• Template Support - ERB templates for HTML and text email versions
• Preview in Development - See emails without sending via /rails/mailers
• Testing Support - Full test suite for delivery and content
• Layouts - Shared layouts for consistent email branding
• Attachments - Send files (PDFs, images) with emails

Before completing mailer work:

• ✅ Async delivery used (deliverlater, not delivernow)
• ✅ Both HTML and text templates provided
• ✅ URL helpers used (not path helpers)
• ✅ Email previews created for development
• ✅ Mailer tests passing (delivery and content)
• ✅ SolidQueue configured for background delivery

• ALWAYS deliver emails asynchronously with deliverlater (NOT delivernow)
• Provide both HTML and text email templates
• Use url helpers (NOT path) for links in emails
• Set default 'from' address in ApplicationMailer
• Create email previews for development (/rails/mailers)
• Configure defaulturloptions for each environment
• Use inline CSS for email styling (email clients strip external styles)
• Test email delivery and content
• Use parameterized mailers (.with()) for cleaner syntax

---

ActionMailer Setup

Configure ActionMailer for email delivery

Mailer Class:

# app/mailers/application_mailer.rb
class ApplicationMailer 
Welcome, !
Thanks for signing up. Get started by logging in:

Text Template:

Welcome, !

Thanks for signing up. Get started by logging in:

Usage (Async with SolidQueue):

# In controller or service
NotificationMailer.welcome_email(@user).deliver_later
NotificationMailer.password_reset(@user).deliver_later(queue: :mailers)

Why: ActionMailer integrates seamlessly with SolidQueue for async delivery. Always use deliver_later to avoid blocking requests. Provide both HTML and text versions for compatibility.

Using deliver_now in production (blocks HTTP request)

# ❌ WRONG - Blocks HTTP request thread
def create
  @user = User.create!(user_params)
  NotificationMailer.welcome_email(@user).deliver_now  # Blocks!
  redirect_to @user
end

# ✅ CORRECT - Async delivery via SolidQueue
def create
  @user = User.create!(user_params)
  NotificationMailer.welcome_email(@user).deliver_later  # Non-blocking
  redirect_to @user
end

Why bad: delivernow blocks the HTTP request until SMTP completes, creating slow response times and poor user experience. deliverlater uses SolidQueue to send email in background.

Use .with() to pass parameters cleanly to mailers

class NotificationMailer 

---

## Email Templates

Shared layouts for consistent email branding

**HTML Layout:**

```erb

  
    
    
      body {
        font-family: Arial, sans-serif;
        max-width: 600px;
        margin: 0 auto;
        color: #333;
      }
      .header {
        background-color: #4F46E5;
        color: white;
        padding: 20px;
        text-align: center;
      }
      .content {
        padding: 20px;
      }
      .button {
        display: inline-block;
        padding: 12px 24px;
        background-color: #4F46E5;
        color: white;
        text-decoration: none;
        border-radius: 4px;
      }
      .footer {
        padding: 20px;
        text-align: center;
        font-size: 12px;
        color: #666;
      }
    
  
  
    
      Your App
    
    
      
    
    
      © 2025 Your Company. All rights reserved.
    
  

Text Layout:

================================================================================
YOUR APP
================================================================================

--------------------------------------------------------------------------------
© 2025 Your Company. All rights reserved.

Why: Consistent branding across all emails. Inline CSS ensures styling works across email clients.

Attach files to emails (PDFs, CSVs, images)

class ReportMailer 

Why: Attach reports, exports, or inline images. Inline attachments can be referenced in email body with image_tag.

Using path helpers instead of url in emails (broken links)

# ❌ WRONG - Relative path doesn't work in emails
def welcome_email(user)
  @user = user
  @login_url = login_path  # => "/login" (relative path)
  mail(to: user.email, subject: "Welcome")
end

# ✅ CORRECT - Full URL works in emails
def welcome_email(user)
  @user = user
  @login_url = login_url  # => "https://example.com/login" (absolute URL)
  mail(to: user.email, subject: "Welcome")
end

# Required configuration
# config/environments/production.rb
config.action_mailer.default_url_options = { host: "example.com", protocol: "https" }

Why bad: Emails are viewed outside your application context, so relative paths don't work. Always use *_url helpers to generate absolute URLs.

---

Email Testing

Preview emails in browser during development without sending

Configuration:

# Gemfile
group :development do
  gem "letter_opener"
end

# config/environments/development.rb
config.action_mailer.delivery_method = :letter_opener
config.action_mailer.default_url_options = { host: "localhost", port: 3000 }

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "smtp.sendgrid.net",
  port: 587,
  user_name: Rails.application.credentials.dig(:smtp, :username),
  password: Rails.application.credentials.dig(:smtp, :password),
  authentication: :plain,
  enable_starttls_auto: true
}
config.action_mailer.default_url_options = { host: "example.com", protocol: "https" }

Why: letter_opener opens emails in browser during development - no SMTP setup needed. Test email appearance without actually sending.

Preview all email variations at /rails/mailers

# test/mailers/previews/notification_mailer_preview.rb
class NotificationMailerPreview 

Test email delivery and content with ActionMailer::TestCase

```ruby
# test/mailers/notification_mailer_test.rb
class NotificationMailerTest 

---

## Email Configuration

Configure ActionMailer for each environment

**Development:**

```ruby
# config/environments/development.rb
config.action_mailer.delivery_method = :letter_opener
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = true
config.action_mailer.default_url_options = { host: "localhost", port: 3000 }

Test:

# config/environments/test.rb
config.action_mailer.delivery_method = :test
config.action_mailer.default_url_options = { host: "example.com" }

Production:

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = false
config.action_mailer.default_url_options = {
  host: ENV["APP_HOST"],
  protocol: "https"
}

config.action_mailer.smtp_settings = {
  address: ENV["SMTP_ADDRESS"],
  port: ENV["SMTP_PORT"],
  user_name: Rails.application.credentials.dig(:smtp, :username),
  password: Rails.application.credentials.dig(:smtp, :password),
  authentication: :plain,
  enable_starttls_auto: true
}

Why: Different configurations per environment. Development previews in browser, test stores emails in memory, production sends via SMTP.

---

# test/mailers/notification_mailer_test.rb
class NotificationMailerTest 

---

- rails-ai:jobs - Background job processing with SolidQueue
- rails-ai:views - Email templates and layouts
- rails-ai:testing - Testing email delivery
- rails-ai:project-setup - Environment-specific email configuration

**Official Documentation:**
- [Rails Guides - Action Mailer Basics](https://guides.rubyonrails.org/action_mailer_basics.html)

**Gems & Libraries:**
- [letter_opener](https://github.com/ryanb/letter_opener) - Preview emails in browser during development

**Tools:**
- [Email on Acid](https://www.emailonacid.com/) - Email testing across clients

**Email Service Providers:**
- [SendGrid Rails Guide](https://docs.sendgrid.com/for-developers/sending-email/rubyonrails)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Shoebtamboli](https://github.com/Shoebtamboli)
- **Source:** [Shoebtamboli/rails_claude_skills](https://github.com/Shoebtamboli/rails_claude_skills)
- **License:** MIT
- **Homepage:** https://rubygems.org/gems/rails_claude_skills

Install and usage instructions live in the source repository linked above.