README.rdoc in rzeszotko-ar_mailer-2.1.10 vs README.rdoc in rzeszotko-ar_mailer-2.1.11

- old
+ new

@@ -1,137 +1,62 @@ -= ar_mailer += ar_mailer (with priority queue) -A two-phase delivery agent for ActionMailer +Ar_mailer is a gem that implements an email queue for Ruby on Rails in +a transparent way. After changing one setting, all of the usual +'deliver_xyz' mailer methods will, instead of actually sending out an +email, create a new row in the 'emails' table which is used as the +queue. A separate daemon checks that table periodically and does the +actual delivery. This can greatly speed up the response time of Rails +actions that are locked for a long time by the process of sending out +large emails. -Rubyforge Project: +This project was forked from: -http://rubyforge.org/projects/seattlerb +https://github.com/adzap/ar_mailer -Documentation: +Which was forked from: -http://seattlerb.org/ar_mailer +http://rubyforge.org/projects/seattlerb -and for forked additions +It adds one additional feature to ar_mailer - the ability to +prioritize emails, so that for example newsletter sending out doesn't +block the sending out of more time-critical email messages. -http://github.com/adzap/ar_mailer/wikis +For general ar_mailer setup instructions see the original sources: -Bugs: +https://github.com/adzap/ar_mailer -http://adzap.lighthouseapp.com/projects/26997-ar_mailer +http://rubyforge.org/projects/seattlerb -== About +== Installing ar_mailer -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. +There is a gem you have to install instead of the usual ar_mailer: -== 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 + $ sudo gem install rzeszotko-ar_mailer -Then +Then in environment.rb you have to do: - $ sudo gem install adzap-ar_mailer + config.gem "rzeszotko-ar_mailer" -For Rails >= 2.1, in your environment.rb: +You may also need to do an additonal require: - config.gem "adzap-ar_mailer", :lib => 'action_mailer/ar_mailer' + require 'rzeszotko-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: +The difference from regular ar_mailer is in that you can specify a +priority for a given email: - $ 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 + class Emails < ActionMailer::Base + def newsletter(newsletter, users) + from "John Doe <john.doe@gmail.com>" + recipients users.collect(&:email) + sent_on Time.now + subject newsletter.subject + priority 100 + body :newsletter => newsletter + end 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. - -=== 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. +Emails with lower priority are send out first, and the default +priority (when you do not specify one explicitly) is 0.