Mailers

Using Merb mailers.

In init.rb, include a dependency on ‘merb-mailer’. The Merb::Mailer docs cover some basic configuration options. As a gotcha, the config option only seems to work right if you stick it in the after_app_loads block, otherwise Merb::Mailer raises a NameError.

Merb::MailController docs have an example of where to put the mailer controller and the views, as well as an example of how to use the send_mail helper.

How Merb mailer is organized.

Merb mailer has idea of separation of mailer logic from mailer templates to the point mailers in Merb have own tiny MVC architecture.

Example of Merb controller:


class UserMailer < Merb::MailController
  def hello
    render_mail
  end  
end

templates are kept under app/views/mail controller name/template name just like with regular controllers. Content types in template name may be either text or html, like in app/mailers/views/user_mailer/hello.text.erb for the mailer controller above:

Hello <%= params[:name] %>

Send methods.

Merb mailer can use SMTP, Sendmail and imitate sendout in test environment. By default Sendmail is used so to use SMTP you have to use config in your application init file. From Merb-mailer documentation:


Merb::Mailer.config = {
  :host   => 'smtp.yourserver.com',
  :port   => '25',              
  :user   => 'user',
  :pass   => 'pass',
  :auth   => :plain # :plain, :login, :cram_md5, the default is no auth
  :domain => "localhost.localdomain" # the HELO domain provided by the client to the server 
}

Configuration example for Gmail SMTP:


Merb::Mailer.config = {
  :host   => 'smtp.gmail.com',
  :port   => '587',
  :user   => 'user@gmail.com',
  :pass   => 'pass',
  :auth   => :plain
}

require smtp_tls
Use :text option instead of :body


m = Merb::Mailer.new :to => 'foo@bar.com',
                     :from => 'bar@foo.com',
                     :subject => 'Welcome to whatever!',
                     :text => partial(:sometemplate)
m.deliver!

Configuration for Sendmail send method takes path to Sendmail:


Merb::Mailer.config = {:sendmail_path => '/opt/local/bin/sendmail'}

Plain text mail, HTML mail and MailFactory wrapping.

Merb::Mailer is a “smart wrapper” around MailFactory. This means you should think 2 or 3 times before operating on @mail.body attribute of mailer instances in your code. To set plain text body use text attribute like this:


Merb::Mailer.new(:to => ..., :from => ..., :subject => ..., :text => "Users with no HTML rendering mail clients will see this").deliver!

and html attribute to set html content:


Merb::Mailer.new(:to => ..., :from => ..., :subject => ..., :html => "Users having HTML rendering mail clients will see this").deliver!

body, to, from and subject fields are proxied to MailFactory when you receive them. Keep this in mind if you wonder why those fields return arrays instead of strings.

Testing mailers.

First off, make sure you use test sending method so emails won’t be sent on each tests run:


Merb::Mailer.delivery_method = :test_send

Useful helper for mailers testing in your controller specs:


send_mail UserMailer, :hello, {
  :from => "greeter@example.com",
  :to => @person.email,
  :subject => "Greetings" 
}, {
  :name => @person.name
}

Another useful helper to test mailers themselves:


def describe_mail(mailer, template, &block)
  describe "/#{mailer.to_s.downcase}/#{template}" do
    before :each do
      @mailer_class, @template = mailer, template
      @assigns = {}
    end

    def deliver(send_params={}, mail_params={})
      mail_params = {:from => "from@example.com", :to => "to@example.com", :subject => "Subject Line"}.merge(mail_params)
      @mailer_class.new(send_params).dispatch_and_deliver @template.to_sym, mail_params
      @mail = Merb::Mailer.deliveries.last
    end

    instance_eval &block
  end
end

Mailer controller specs may look like this then:


require File.join(File.dirname(__FILE__),'..','spec_helper')

describe_mail UserMailer, :hello do
  it "should say hello" do
    deliver :name => "Jamie" 
    @mail.text.should == "Hello Jamie" 
  end
end

Massive mail sendouts, mail queueing.

If you need to send out more than one email, it may become a bottleneck of your action. Classic example is forum notifications on new replies: sending out 100 email in action may take fair number of seconds. In Merb with Mongrel you can use render_then_call method to “release” Mongrel and then do actual send out:


def create
  # ...
  rendered_template = render :template => :posted
  render_then_call(rendered_template) do
    # do emails sending
  end
end

But because this example above does not work with Thin and Ebb (at least, 0.8.1 and 0.2 versions, respectively) you may consider using mail queue plugin that stores email jobs in the database and provides simple processor to do cron scheduled sendouts.

Merb Wiki