File: README.rdoc [padrino-mailer-0.12.5 Documentation]

### Home Classes Methods

### Files

- README.rdoc

### Class Index

Quicksearch

- Padrino
- Padrino::Mailer
- Padrino::Mailer::Base
- Padrino::Mailer::Helpers
- Padrino::Mailer::Helpers::ClassMethods
- Padrino::Mailer::Mime
- Mail
- Mail::Message

No matching classes.

# 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, "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 guide for more details on usage.

## Copyright

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.