README.rdoc

Simple Mailer Support (padrino-mailer)¶ ↑

Overview¶ ↑

This component creates an easy and intuitive interface for delivering email within a Sinatra application. The mail library is utilized to do the bulk of the work. There is full support for rendering email templates, using an html content type and for file attachments. The Padrino Mailer uses a familiar Sinatra syntax similar to that of defining routes for a controller.

Usage¶ ↑

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

# Example for configuring gmail smtp
set :delivery_method, :smtp => {
  :address              => "smtp.gmail.com",
  :port                 => 587,
  :domain               => 'your.host.name',
  :user_name            => '<username>',
  :password             => '<password>',
  :authentication       => 'plain',
  :enable_starttls_auto => true
}

Once the delivery settings have been defined, the default will become smtp delivery but can be overwritten in each message.

Padrino supports sending quick emails (using either sendmail or smtp) right from your controllers. This is ideal for ‘one-off’ emails where the ‘full’ mailer declaration is simply unnecessary.

Delivering an email from within your controller is simple:

# app/controllers/session.rb
post :create do
  email(:to => "john@smith.com", :subject => "Successfully Registered!", :body => "Test Body")
end

Padrino also supports structured mailer declarations. We can define a new mailer using a mailer block.

# app/mailers/sample_mailer.rb
MyAppName.mailers :sample do
  email :registration do |name|
    from    'admin@site.com'
    to      'user@domain.com'
    subject 'Welcome to the site!'
    locals  :name => name
    content_type 'html'        # optional, defaults to plain/text
    charset 'windows-1252'     # optional, defaults to utf-8
    via     :sendmail          # optional, smtp if defined otherwise sendmail
    render  'registration'
  end
end

In addition to a standard body, Padrino also easily supports multi-part emails:

# app/mailers/sample_mailer.rb
MyAppName.mailers :sample do
  email :registration do |name|
    to      'padrino@test.lindsaar.net'
    subject "nested multipart"
    from    "test@example.com"

    text_part { render('multipart/basic.plain') }
    html_part { render('multipart/basic.html')  }
  end
end

Defaults can also be declared on a per-mailer or app-wide basis:

# app/app.rb
set :mailer_defaults, :from => 'admin@site.com'

# app/mailers/sample_mailer.rb
MyAppName.mailers :sample do
  defaults :content_type => 'html'
  email :registration do |name, age|
    # Uses default 'content_type' and 'from' values but can also overwrite them
    to      'user@domain.com'
    subject 'Welcome to the site!'
    locals  :name => name
    render  'registration'
  end
end

This defines a message called ‘registration’ with the specified attributes. The body method is invoking the render function passing the name attribute to the body message template which is defined in [views_path]/mailers/sample/registration.erb as shown below:

# ./views/mailers/sample/registration.erb
This is the body of the email and can access the <%= name %> that was passed in from the mailer definition
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:

deliver(:sample, :registration_email, "Bob", "21")

And that will then deliver the email according the the configured options. This is all you need to send basic emails.

The mailer also supports the attachment of files and various other options. Be sure to check out the Padrino Mailer guide for more details on usage.

Copyright¶ ↑

Copyright © 2010 Padrino. See LICENSE for details.