= ar_mailer

A two-phase delivery agent for ActionMailer

Rubyforge Project:

http://rubyforge.org/projects/seattlerb

Documentation:

http://seattlerb.org/ar_mailer

and for forked additions

http://github.com/adzap/ar_mailer/wikis

Bugs:

http://adzap.lighthouseapp.com/projects/26997-ar_mailer

== About

Even delivering email to the local machine may take too long when you have to
send hundreds of messages.  ar_mailer allows you to store messages into the
database for later delivery by a separate process, ar_sendmail.

== Installing ar_mailer (forked)

Before installing you will need to make sure the original gem is uninstalled as they can't coexist:

  $ sudo gem uninstall ar_mailer

Then

  $ sudo gem install adzap-ar_mailer

For Rails >= 2.1, in your environment.rb:

  config.gem "adzap-ar_mailer", :lib => 'action_mailer/ar_mailer'

  # or since version 2.1.7 of this gem you can now just do

  config.gem "adzap-ar_mailer"

For Rails 2.0, in an initializer file:

  require 'action_mailer/ar_mailer'

== Usage

Go to your Rails project:

  $ cd your_rails_project

Create the migration and model:

This shows the options which are only the model name, which defaults to Email

  ./script/generate ar_mailer -h

Then run with defaults

  ./script/generate ar_mailer

Or specify a custom model name

  ./script/generate ar_mailer Newsletter

See Alternate Mail Storage if you use a custom model name

In your mailer class methods you must be sure to set the From address for your emails.
Something like:

  def list_send(recipient)
    from 'no_reply@example.com'
    # ...

Edit config/environments/production.rb and set the delivery method:

  config.action_mailer.delivery_method = :activerecord

Or if you need to, you can set each mailer class delivery method individually:

  class MyMailer < ActionMailer::Base
    self.delivery_method = :activerecord
  end

This can be useful when using plugins like ExceptionNotification. Where it
might be foolish to tie the sending of the email alert to the database when the
database might be causing the exception being raised. In this instance you could
override ExceptionNofitier delivery method to be smtp or set the other
mailer classes to use ARMailer explicitly.

Then to run it:

  $ ar_sendmail

You can also run it from cron with -o, or as a daemon with -d.

See <tt>ar_sendmail -h</tt> for full details.

=== Alternate Mail Storage

By default ar_mailer assumes you are using an ActiveRecord model called
Email to store the emails created before sending. If you want to change
this you alter it in an intializer like so:

  ActionMailer::Base.email_class = Newsletter

=== A Word on TLS

If you are using Ruby >= 1.8.7, TLS will be enabled automatically if your
SMTP server supports it. If you do not want it to automatically enabled then
set the :tls option to false in your smtp_settings.

If you are on Ruby <= 1.8.6, then the TLS patch included in this plugin will
be loaded, so you don't need another TLS plugin to add the capability. This
patch allows you to explicit set if the server supports TLS by setting the
:tls option to true in your smtp_settings.


=== EXPERIMENTAL: Minimal environment loading

The biggest downside to using ar_mailer is that it loads the entire Rails app
into memory. For larger apps this can be just a whole lot of wasted memory
given all you need is to access the email table and mailer settings. We can
get around this using a few conventions and save around 50% or more of the
memory used when loading the full app.

Loading the database is not much of a problem since the config sits in its own
yaml which is easy to load in isolation from the app. The mailer settings are
trickier since they are usually in the environment file which depends on loading
the Railties system and therefore the whole app.

To workaround for this we need to put all the SMTP settings in a yaml config
file like the database settings. Like so

in config/email.yml

  development:
    domain: example.com
    address: smtp.example.com
    port: 25

  production:
    domain: example.com
    address: smtp.example.com
    port: 25

You can still have ActionMailer settings in each environment file but just be sure
they don't override these SMTP settings. The other settings aren't needed when
running ar_sendmail since they only apply to the generation of an email which has
already happened inside the running application.

To avoid duplication of these settings you need to have an initializer which will
will read the same config file and load these settings. This is in case you switch
back the normal environment loading. Keeping the email settings here is good idea,
since just the like the database, they are external connection settings being stored
in the config folder.

The initializer in config/initializers/action_mailer.rb:

  config_file = "#{Rails.root}/config/email.yml"
  mailer_options = YAML::load(ERB.new(IO.read(config_file)).result)
  if mailer_options[Rails.env]
    ActionMailer::Base.smtp_settings = mailer_options[Rails.env].symbolize_keys
  end

At the moment if you are using a database driver that doesn't come with Rails, the gem
will need to be installed on the target system.

Now to run ar_sendmail with minimal environment we do:

  ar_sendmail -e production -c /path/to/app --minimal

If you have any troubles or find any bad assumptions in the minimal set up let me know.


=== Help

See ar_sendmail -h for options to ar_sendmail.

NOTE: You may need to delete an smtp_tls.rb file if you have one lying
around.  ar_mailer supplies it own.

== Run as a service (init.d/rc.d scripts)

For Linux both script and demo config files are in share/linux.
See ar_sendmail.conf for setting up your config. Copy the ar_sendmail file
to /etc/init.d/ and make it executable. Then for Debian based distros run
'sudo update-rc.d ar_sendmail defaults' and it should work. Make sure you have
the config file /etc/ar_sendmail.conf in place before starting.

For FreeBSD or NetBSD script is share/bsd/ar_sendmail. This is old and does not
support the config file unless someone wants to submit a patch.