Rails Action Mailer

Master email delivery in Rails applications with Action Mailer, from basic setup through advanced patterns like multipart emails, attachments, and email testing.

When to Use This Skill

Sending transactional emails (welcome, password reset, confirmations)
Building notification emails (order updates, alerts, reminders)
Creating bulk email campaigns
Handling email attachments and inline images
Configuring SMTP, SendGrid, or other delivery services
Testing email content and delivery
Building email templates with HTML and text alternatives
Managing email callbacks and error handling

Quick Start

Generate and send a welcome email:

rails generate mailer User welcome_email

Create a mailer:

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  default from: "notifications@example.com"

  def welcome_email
    @user = params[:user]
    @url = "http://example.com/login"
    mail(to: @user.email, subject: "Welcome to My Site")
  end
end

Create the email template:

<!-- app/views/user_mailer/welcome_email.html.erb -->
<h1>Welcome <%= @user.name %></h1>
<p>You have successfully signed up. Log in here: <%= link_to 'login', @url %></p>

Send the email from a controller:

class UsersController < ApplicationController
  def create
    @user = User.new(user_params)
    if @user.save
      UserMailer.with(user: @user).welcome_email.deliver_later
      redirect_to @user, notice: "Welcome email sent"
    end
  end
end

Core Topics

Mailer Setup & Views: See mailers-views.md for generating mailers, creating templates, using layouts, URL generation, and email helpers.

Sending Emails: See sending-emails.md for deliver_now vs deliver_later, multiple recipients, attachments, multipart emails, and dynamic delivery options.

Configuration: See configuration.md for SMTP setup, Gmail configuration, delivery methods, and environment-specific settings.

Callbacks & Interceptors: See callbacks-interceptors.md for before/after action callbacks, before/after deliver, email interception, and email observation.

Testing & Previews: See testing.md for email previews, unit testing mailers, ActionMailer assertions, and integration testing.

Advanced Patterns: See references/advanced-patterns.md for scheduled emails with Active Job, error handling, custom delivery agents, and production best practices.

Examples

See examples.md for practical, real-world implementations including:

Welcome and password reset emails
Order confirmation and shipping notifications
Bulk newsletter campaigns
Emails with attachments and inline images
Error handling and retry logic

Key Concepts

Mailers as Controllers

Mailers work similarly to controllers:

Instance variables accessible in views
Can use layouts and partials
Access to params hash
Actions correspond to email types
Views in app/views/mailer_name/

Parameterized Mailers

Pass data to mailers using with:

UserMailer.with(user: @user, token: @token).reset_password_email

Access in the mailer action:

def reset_password_email
  @user = params[:user]
  @token = params[:token]
  mail(to: @user.email, subject: "Reset Your Password")
end

Delivery Methods

Control how emails are sent:

# config/environments/production.rb
config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "smtp.gmail.com",
  port: 587,
  user_name: "your-email@gmail.com",
  password: "your-password",
  authentication: "plain",
  enable_starttls: true
}

Active Job Integration

deliver_later enqueues emails as jobs:

# Sends immediately
UserMailer.with(user: @user).welcome_email.deliver_now

# Sends in background via Active Job
UserMailer.with(user: @user).welcome_email.deliver_later

# Sends at a specific time
UserMailer.with(user: @user).welcome_email.deliver_later(wait_until: 1.hour.from_now)

Connections to Other Skills

Rails Active Job: Queue emails for background delivery with proper error handling and retries
Rails Active Record: Query users or other models for email campaigns
Rails Action Controller: Trigger emails from controller actions on create/update events
Rails Testing with RSpec: Test mailers with integration tests and email assertions