Action Mailer

Active contributors: rafaelfranca, jeremy, jonhefner

Purpose

Action Mailer generates and sends email. A mailer is a class with public methods that build a message via the mail DSL, render templates via Action View, and deliver via the mail gem.

Source: actionmailer/lib/action_mailer/. ~2,800 lines of lib/ Ruby.

Directory layout

actionmailer/
├── lib/
│   └── action_mailer/
│       ├── base.rb                       # ActionMailer::Base
│       ├── callbacks.rb
│       ├── collector.rb                  # Format negotiation (HTML vs text)
│       ├── delivery_methods.rb           # smtp, sendmail, file, test
│       ├── form_builder.rb
│       ├── inline_preview_interceptor.rb
│       ├── log_subscriber.rb
│       ├── mail_delivery_job.rb          # ActiveJob-backed delivery
│       ├── mail_helper.rb
│       ├── message_delivery.rb           # Lazy delivery proxy
│       ├── parameterized.rb              # `with(arg: val).welcome` API
│       ├── preview.rb                    # Mailer previews
│       ├── queued_delivery.rb
│       ├── railtie.rb
│       ├── rescuable.rb
│       ├── structured_event_subscriber.rb
│       └── test_helper.rb
└── actionmailer.gemspec

Key abstractions

Constant	File	Purpose
ActionMailer::Base	actionmailer/lib/action_mailer/base.rb	Subclass for every mailer
ActionMailer::MessageDelivery	actionmailer/lib/action_mailer/message_delivery.rb	Lazy proxy returned from MailerClass.method_name(args)
ActionMailer::Parameters (Parameterized)	actionmailer/lib/action_mailer/parameterized.rb	The with(...) style API
ActionMailer::Preview	actionmailer/lib/action_mailer/preview.rb	Browser-renderable mailer previews
ActionMailer::DeliveryMethods	actionmailer/lib/action_mailer/delivery_methods.rb	Pluggable senders (smtp, sendmail, file, test)
ActionMailer::MailDeliveryJob	actionmailer/lib/action_mailer/mail_delivery_job.rb	Active Job-backed deliver_later

How it works

sequenceDiagram
    participant App
    participant Mailer as UserMailer
    participant Base as ActionMailer::Base
    participant View as ActionView
    participant Delivery as DeliveryMethod
    App->>Mailer: UserMailer.welcome(user).deliver_now
    Mailer->>Base: invoke action method
    Base->>Base: process headers, attachments
    Base->>View: render template
    View-->>Base: HTML/text body
    Base->>Delivery: send Mail::Message
    Delivery-->>App: result

MailerClass.action(args) returns a MessageDelivery proxy without doing any work. The actual rendering and SMTP work happens when you call deliver_now or deliver_later. This makes parameterized mailers ergonomic and lets deliver_later enqueue without rendering the message twice.

Delivery methods

actionmailer/lib/action_mailer/delivery_methods.rb registers four built-in delivery methods:

• :smtp — uses the mail gem's SMTP transport.
• :sendmail — pipes to /usr/sbin/sendmail.
• :file — writes to tmp/mails/.
• :test — appends to ActionMailer::Base.deliveries (used in tests).

Third-party gems can register more (Mailgun, Postmark, SES, etc.) via:

ActionMailer::Base.add_delivery_method(:postmark, Mail::Postmark, api_token: ENV["POSTMARK_TOKEN"])

Active Job integration

deliver_later wraps the mailer call in ActionMailer::MailDeliveryJob and pushes to the configured queue adapter. The job re-instantiates the mailer and sends the message. Implementation in actionmailer/lib/action_mailer/mail_delivery_job.rb.

Previews

ActionMailer::Preview (actionmailer/lib/action_mailer/preview.rb) renders mailers in the browser at /rails/mailers/<preview> in development. Rails::MailersController (railties/lib/rails/mailers_controller.rb) hosts the routes.

Action View integration

A mailer instance has a ActionView::Renderer configured with the mailer's view paths (app/views/<mailer_name>/). mail accepts a body:, a template:, or no args (rendering by convention). Format negotiation between HTML and text parts is in collector.rb.

mail_helper.rb adds attachments, format, and other helpers usable inside mailer templates.

Integration points

• Active Job: MailDeliveryJob is the bridge. deliver_later_queue_name and deliver_later_queue_priority are configurable.
• Action View: mailer rendering uses the same LookupContext machinery as controllers.
• Active Support: Notifications publishes deliver.action_mailer and process.action_mailer events.
• Active Storage: attachments via attachments[name] = blob.download work because Active Storage proxies through Active Record.

Entry points for modification

• Adding a delivery method: Subclass Mail::SMTP-style or any class that implements deliver!(mail). Register via add_delivery_method.
• Modifying preview behavior: edit ActionMailer::Preview and the corresponding controller in railties/lib/rails/mailers_controller.rb.
• Adding a callback: declare via before_action, after_action, around_action (provided by ActionMailer::Callbacks).

Related pages

• packages/action-mailbox — the inbound counterpart.
• packages/active-job — what deliver_later enqueues onto.
• packages/action-view — rendering pipeline.