actionmailer-baseline

ActionMailer Baseline

Send email from a Rails 8 app without four classic mistakes: blocking the request thread, double-sending on retry, leaking PII in logs, or rendering broken HTML that bounces. AI agents reach for ActionMailer::Base.mail with deliver_now by default and stop there. This skill covers the rest.

Why this matters

Email is the integration most teams underestimate. It's external infrastructure (SMTP, vendor APIs), it has rate limits, it has bounce rules, it has spam-trap consequences. Doing it casually means either sluggish requests, lost mail, or your domain on a deny-list.

The opinion

deliver_later is the default. Never deliver_now in the request path. Mailer previews wired in development. Postmark / SendGrid / SES / Mailgun via the vendor's Rails adapter; don't roll your own SMTP. Bounce + complaint handling required for any user-facing app at scale. Idempotency on transactional sends (password reset link generated once per request, not per retry). PII filtered from logs and error reports.

Counter-positions:

• deliver_now is legitimate in tests (synchronous) and in admin tools (where blocking the admin user 200ms is fine). Never in user-facing request paths.
• Action Mailbox for receiving email — different scope (deferred to v0.2). This skill covers sending.

Core patterns

Pattern 1: Generate + set up

bin/rails generate mailer UserMailer welcome reset_password

# app/mailers/application_mailer.rb
class ApplicationMailer < ActionMailer::Base
  default from: ENV.fetch("MAILER_FROM", "[email protected]")
  layout "mailer"
end

# app/mailers/user_mailer.rb
class UserMailer < ApplicationMailer
  default template_path: "user_mailer"  # explicit; not required but reads better

  def welcome(user)
    @user = user
    @url = sign_in_url
    mail(to: @user.email, subject: I18n.t("mailers.user.welcome.subject"))
  end

  def reset_password(user, raw_token)
    @user = user
    @reset_url = edit_password_reset_url(token: raw_token)
    mail(to: @user.email, subject: I18n.t("mailers.user.reset_password.subject"))
  end
end