MailerPlugin

Introduction

This component uses an enhanced version of the excellent pony library (vendored) for a powerful but simple mailer system within Sinatra. There is full support for using an html content type as well as for file attachments. The MailerPlugin has many similarities to ActionMailer but is much lighter-weight and (arguably) easier to use.

Setup

# app.rb
require 'sinatra/base'
require 'sinatra_more'

class Application < Sinatra::Base
  # ...
  register SinatraMore::MailerPlugin
 # ...
end

Usage

Let’s take a look at using the MailerPlugin in an application. By default, MailerPlugin uses the built-in sendmail functionality on the server. However, smtp is also supported using the following configuration:

# config/initializers/mailer.rb
SinatraMore::MailerBase.smtp_settings = {
    :host   => 'smtp.gmail.com',
    :port   => '587',
    :tls    => true,
    :user   => 'user',
    :pass   => 'pass',
    :auth   => :plain
 }

Once those have been defined, the default will become smtp delivery unless overwritten in an individual mail definition. Next, we should define a custom mailer extended from SinatraMore::MailerBase.

# app/mailers/sample_mailer.rb
class SampleMailer < SinatraMore::MailerBase
  def registration_email(name, user_email_address)
    from '[email protected]'
    to user_email_address
    subject 'Welcome to the site!'
    body    :name => name
    type    'html'   # optional, defaults to plain/text
    charset 'windows-1252'   # optional, defaults to utf-8
    via     :sendmail  # optional, to smtp if defined otherwise sendmail
  end
end

This defines a mail called ‘registration_mail’ with the specified attributes for delivery. The body method is passing the name attribute to the body message template which should be defined in [views_path]/sample_mailer/registration_email.erb as shown below:

# ./views/sample_mailer/registration_email.erb
This is the body of the email and can access the <%= name %>
That's all there is to defining the body of the email 
which can be plain text or html

Once the mailer definition has been completed and the template has been defined, the email can be sent using:

SampleMailer.deliver(:registration_email, "Bob", "[email protected]")

or if you like the method_missing approach:

SampleMailer.deliver_registration_email "Bob", '[email protected]'

And that will then deliver the email according the the configured options. This is really all you need to send emails. A few variations are shown below for completeness.

If we want to attach files to our email:

# app/mailers/sample_mailer.rb
class SampleMailer < SinatraMore::MailerBase
 def attachment_email(name, user_email_address)
    from '[email protected]'
    to user_email_address
    # ...
    attachments { "foo.zip" => File.read("path/to/foo.zip"), 
                           "file.txt" => "this is a text file!" }
  end
end

or perhaps we want to have a short body without the need for a template file:

# app/mailers/sample_mailer.rb
class SampleMailer < SinatraMore::MailerBase
  def short_email(name, user_email_address)
    from '[email protected]'
    to user_email_address
    subject 'Welcome to the site!'
    body    "This is a short body defined right in the mailer itself"
  end
end