Mailer Patterns

Mailer Patterns

Philosophy: Minimal Mailers, Bundled Notifications

• Plain-text first, minimal HTML styling with inline CSS
• Bundle notifications instead of sending one email per event
• Transactional emails only (no marketing campaigns)
• deliver_later for individual emails; deliver_now is acceptable inside background jobs that already run asynchronously (e.g., digest delivery jobs)
• Email previews for development
• No email service abstraction layers (use Action Mailer directly)

Project Knowledge

Stack: Action Mailer (built-in), Solid Queue for background delivery, email previews in development, plain text + HTML multipart emails.

Multi-tenancy: Account-scoped emails, from address includes account context, unsubscribe links scoped to account.

Commands:

rails generate mailer Comment mentioned         # Generate mailer
rails generate mailer Digest daily_activity      # With methods
# Visit http://localhost:3000/rails/mailers      # Preview emails

Pattern 1: Simple Transactional Mailers

# app/mailers/application_mailer.rb
class ApplicationMailer ")
  layout "mailer"
end

# app/mailers/comment_mailer.rb
class CommentMailer 
Hi ,

 mentioned you in a comment on :

""

View the card: 

---
You're receiving this because you were mentioned.

Hi ,

 mentioned you in a comment on
   :

  

Pattern 3: Bundled Notifications (Digest Emails)

See @references/bundled-notifications.md for full details.

# app/mailers/digest_mailer.rb
class DigestMailer = 5 ||
      oldest_pending_notification_age > 1.hour
  end

  def send_digest
    return unless should_send_digest?
    notifications = pending_notifications
    DigestMailer.pending_notifications(@user, notifications).deliver_later
    notifications.update_all(sent_at: Time.current)
  end

  private

  def pending_notifications
    @user.notifications.where(sent_at: nil)
      .where("created_at > ?", 1.hour.ago)
      .order(created_at: :desc)
  end
end

# app/jobs/send_digest_emails_job.rb
class SendDigestEmailsJob 

---

  
    
    
    
      body { margin: 0; padding: 0; font-family: -apple-system, sans-serif;
             font-size: 16px; line-height: 1.5; color: #333; background: #f5f5f5; }
      a { color: #0066cc; }
    
  
  
    
      
      
        
      
    
  

Delivery Configuration

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

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

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

Boundaries

Always

• Create both .text.erb and .html.erb templates
• Use deliver_later for individual emails; deliver_now is acceptable inside background jobs that already run asynchronously (e.g., digest delivery jobs)
• Check user email preferences before sending
• Include unsubscribe links in emails
• Use inline CSS for HTML emails (no external stylesheets)
• Scope emails to account context
• Create email previews for development

Ask First

• Digest frequency and bundling thresholds
• Whether to include inline attachments (logos)
• SMTP provider configuration

Never

• Send one email per event (bundle notifications)
• Mix marketing and transactional emails
• Use external CSS in email templates
• Build email service abstraction layers
• Send emails synchronously in request cycle
• Skip email preferences check

Source & license

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

• Author: ThibautBaissac
• Source: ThibautBaissac/railsai_agents
• License: MIT
• Homepage: https://thibautbaissac.github.io/

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