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.

<when-to-use>

• 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

</when-to-use>

<benefits>

• 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

</benefits>

<verification-checklist> Before completing mailer work:

• ✅ Async delivery used (deliver_later, not deliver_now)
• ✅ 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

</verification-checklist>

<standards>

• ALWAYS deliver emails asynchronously with deliver_later (NOT deliver_now)
• 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 default_url_options 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

</standards>

ActionMailer Setup

<pattern name="actionmailer-basic-setup"> <description>Configure ActionMailer for email delivery</description>

Mailer Class:

# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  default from: "noreply@example.com"
  layout "mailer"
end

# app/mailers/notification_mailer.rb
class NotificationMailer < ApplicationMailer
  def welcome_email(user)
    @user = user
    @login_url = login_url
    mail(to: user.email, subject: "Welcome to Our App")
  end

  def password_reset(user)
    @user = user
    @reset_url = password_reset_url(user.reset_token)
    mail(to: user.email, subject: "Password Reset Instructions")
  end
end

HTML Template:

<%# app/views/notification_mailer/welcome_email.html.erb %>
<h1>Welcome, <%= @user.name %>!</h1>
<p>Thanks for signing up. Get started by logging in:</p>
<%= link_to "Login Now", @login_url, class: "button" %>

Text Template:

<%# app/views/notification_mailer/welcome_email.text.erb %>
Welcome, <%= @user.name %>!

Thanks for signing up. Get started by logging in:
<%= @login_url %>

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. </pattern>

<antipattern> <description>Using deliver_now in production (blocks HTTP request)</description> <bad-example>

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

</bad-example> <good-example>

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

</good-example>

Why bad: deliver_now blocks the HTTP request until SMTP completes, creating slow response times and poor user experience. deliver_later uses SolidQueue to send email in background. </antipattern>

<pattern name="parameterized-mailers"> <description>Use .with() to pass parameters cleanly to mailers</description>

class NotificationMailer < ApplicationMailer
  def custom_notification
    @user = params[:user]
    @message = params[:message]
    mail(to: @user.email, subject: params[:subject])
  end
end

# Usage
NotificationMailer.with(
  user: user,
  message: "Update available",
  subject: "System Alert"
).custom_notification.deliver_later

Why: Cleaner syntax, easier to read and modify, and works seamlessly with background jobs. </pattern>

Email Templates

<pattern name="email-layouts"> <description>Shared layouts for consistent email branding</description>

HTML Layout:

<%# app/views/layouts/mailer.html.erb %>
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <style>
      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;
      }
    </style>
  </head>
  <body>
    <div class="header">
      <h1>Your App</h1>
    </div>
    <div class="content">
      <%= yield %>
    </div>
    <div class="footer">
      <p>&copy; 2025 Your Company. All rights reserved.</p>
    </div>
  </body>
</html>

Text Layout:

<%# app/views/layouts/mailer.text.erb %>
================================================================================
YOUR APP
================================================================================

<%= yield %>

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

Why: Consistent branding across all emails. Inline CSS ensures styling works across email clients. </pattern>

<pattern name="email-attachments"> <description>Attach files to emails (PDFs, CSVs, images)</description>

class ReportMailer < ApplicationMailer
  def monthly_report(user, data)
    @user = user

    # Regular attachment
    attachments["report.pdf"] = {
      mime_type: "application/pdf",
      content: generate_pdf(data)
    }

    # Inline attachment (for embedding in email body)
    attachments.inline["logo.png"] = File.read(
      Rails.root.join("app/assets/images/logo.png")
    )

    mail(to: user.email, subject: "Monthly Report")
  end
end

In template:

<%# Reference inline attachment %>
<%= image_tag attachments["logo.png"].url %>

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

<antipattern> <description>Using *_path helpers instead of *_url in emails (broken links)</description> <bad-example>

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

</bad-example> <good-example>

# ✅ 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" }

</good-example>

Why bad: Emails are viewed outside your application context, so relative p