= 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 <tt>mailer</tt> 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 '<tt>registration</tt>' with the specified attributes. The <tt>body</tt> method
is invoking the render function passing the <tt>name</tt> attribute to the body message template which is defined in
<tt>[views_path]/mailers/sample/registration.erb</tt> 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, "Bob", "21")

And that will then deliver the email according 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}[http://www.padrinorb.com/guides/padrino-mailer] guide for more details on usage.

== Copyright

Copyright (c) 2011-2013 Padrino. See LICENSE for details.
