= padrino-mailer

This component uses an enhanced version of the excellent <tt>pony</tt> library (vendored) for a powerful but simple
mailer system within Padrino (and 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 lighterweight and (arguably) easier to use.

== Installation

To install the 'full-stack' padrino framework, simply grab the latest version from gemcutter:

  $ sudo gem install padrino --source http://gemcutter.org
  
This will install the necessary padrino gems to get you started.
Now you are ready to use this gem to enhance your existing Sinatra projects or build new Padrino applications.

You can also install only the padrino-mailer gem for more fine-grained use:

  $ sudo gem install padrino-mailer --source http://gemcutter.org
  
== 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:

    Padrino::Mailer::Base.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 <tt>Padrino::Mailer::Base</tt>.

  # app/mailers/sample_mailer.rb
  class SampleMailer < Padrino::Mailer::Base
    def registration_email(name, user_email_address)
      from 'admin@site.com'
      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 '<tt>registration_mail</tt>' with the specified attributes for delivery. The <tt>body</tt> method
is passing the <tt>name</tt> attribute to the body message template which should be defined in
<tt>[views_path]/sample_mailer/registration_email.erb</tt> as shown below:

  # ./views/sample_mailer/registration_email.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:

  SampleMailer.deliver(:registration_email, "Bob", "bob@bobby.com")

or if you like the method_missing approach:

  SampleMailer.deliver_registration_email "Bob", 'bob@bobby.com'

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 < Padrino::Mailer::Base
    def attachment_email(name, user_email_address)
      from 'admin@site.com'
      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 < Padrino::Mailer::Base
    def short_email(name, user_email_address)
      from 'admin@site.com'
      to user_email_address
      subject 'Welcome to the site!'
      body    "This is a short body defined right in the mailer itself"
    end
  end

See the wiki article for additional information: <...WIKI...>

== Copyright

Copyright (c) 2009 Padrino. See LICENSE for details.