README.md

IdleMailer

A lightweight (~200 line) alternative to ActionMailer for Rubyists who are too cool for Rails. Powered by the mail gem. Great for API-only backends that need to send email.

Installation

Add to your Gemfile.

gem 'idlemailer'

Use

IdleMailer provides mailer classes and templates on top of the mail gem. mail has a great API, so you have unfettered access to it in your mailers.

# Define your mailer class
class WidgetMailer
  include IdleMailer::Mailer

  def initialize(user, widget)
    @widget = widget
    mail.to = user.email
    mail.subject = "Widget #{widget.sku}"
    # 'mail' is just a Mail object from the mail gem, so you can use the
    # full Mail api here, e.g. to, subject, attachments, etc.
  end
end

# Create widget.html.erb and/or widget.text.erb in your templates directory.
# They'll have access to instance variables like @widget above, as well as any methods you define.

# Send your mail
WidgetMailer.new(current_user, widget).deliver

HTML escaping

All values will be automatically HTML-escaped. If you need to bypass escapeing, use the raw helper:

<%= raw @something_with_safe_html %>

Inline templates

If you prefer, you can embed your ERB templates right inside your Ruby class, instead of making separate template files. Slick amiright?

class WidgetMailer
  include IdleMailer::Mailer

  # optionally override the default layout
  self.layout = "widget_layout"

  def initialize(user, widget)
    @widget = widget
    mail.to = user.email
    mail.subject = "Widget #{widget.sku}"
  end

  text %(
A new widget called <%= @widget %> was just created!

Thanks!
  )

  html %(
<p>A new widget called <%= @widget %> was just created!</p>

<p>Thanks!</p>
  )
end

Configure

These are the default options. Salt to taste.

IdleMailer.config do |config|
  # Directory containing the mailer templates
  config.templates = Pathname.new(Dir.getwd).join('templates')

  # Pre-cache all templates and layouts (instead of re-loading them on each delivery)
  config.cache_templates = true

  # Name of the default layout template. Here, the file(s) would be named
  # mailer_layout.html.erb and/or mailer_layout.text.erb.
  config.layout = 'mailer_layout'

  # Email delivery method (mail gem). Set to :test when testing or when developing locally
  config.delivery_method = :smtp

  # Delivery options (mail gem)
  config.delivery_options = {
    user_name: ENV['MAIL_USER'],
    password: ENV['MAIL_PASSWORD'],
    domain: ENV['MAIL_DOMAIN'],
    address: ENV['MAIL_ADDRESS'],
    port: ENV['MAIL_PORT'] || 587,
    authentication: ENV['MAIL_AUTHENTICATION'] || 'plain',
    enable_starttls_auto: (ENV['MAIL_TLS'] ? true : false)
  }

  # Default "from" address for all mailers
  config.default_from = nil

  # Log sent emails (require 'logger')
  # config.logger = Logger.new($stdout)
  # config.logger = Logger.new('log/mailers.log')
  config.logger = nil

  # Write full message body to log (if enabled). Otherwise, only message headers are logged.
  config.log_body = false
end

Testing

Put the mailer into testing mode:

IdleMailer.config do |config|
  config.delivery_method = :test
end

Then configure your test runner. Here's an example with RSpec:

RSpec.configure do |config|
  # Clear sent mail after every test
  config.after :each do
    IdleMailer::Testing.clear_mail!
  end

  # Include the test helpers in your specs
  config.include IdleMailer::Testing::Helpers
end

Your tests will have access to these helper methods. (Note you can also call them directly on IdleMailer::Testing as well)

# quick boolean checks
sent_mail_to? '[email protected]'
sent_mail_to? '[email protected]', /subject/
sent_mail_to? '[email protected]', /subject/, /body/
sent_mail_with_subject? /Foo/
sent_mail_with_body? /Bar/
sent_mail_from? '[email protected]'

# get arrays of matching sent mail (Mail::Message objects)
mail_to '[email protected]'
mail_to '[email protected]', /subject/
mail_to '[email protected]', /subject/, /body/
mail_with_subject /Foo/
mail_with_body /Bar/
mail_from '[email protected]'

# get an array of all sent mail
sent_mail

# clear all sent mail
clear_mail!

License

MIT License. See LICENSE for details.

Copyright

Copyright (c) 2015 Jordan Hollinger