= has_emails

+has_emails+ demonstrates a reference implementation for sending emails with
logging and asynchronous support.

== Resources

Wiki

* http://wiki.pluginaweek.org/Has_emails

API

* http://api.pluginaweek.org/has_emails

Development

* http://dev.pluginaweek.org/browser/trunk/has_emails

Source

* http://svn.pluginaweek.org/trunk/has_emails

== Description

Emailing between users and other parts of a system is a fairly common feature in
web applications, especially for those that support social networking.  Emailing
doesn't necessarily need to be between users, but can also act as a way for the
web application to send notices and other notifications to users.

Rails already provides ActionMailer as a way of sending emails.  However, the
framework does not provide an easy way to persist emails, track their status, and
process them asynchronously.  Designing and building a framework that supports this
can be complex and takes away from the business focus.  This plugin can help ease
that process by demonstrating a complete implementation of these features.

== Usage

=== Creating new emails

Emails should usually still be created using ActionMailer.  However, instead of
delivering the emails, you can queue the emails like so:

  Notifier.deliver_signup_notification(david) # sends the email now
  Notifier.queue_signup_notification(david) # sends the email later (has_emails kicks in)

In addition to queueing emails, you can build them directly like so:

  email_address = EmailAddress.find(123)
  email = email_address.emails.build
  email.to EmailAddress.find(456)
  email.subject = 'Hey!'
  email.body = 'Does anyone want to go out tonight?'
  email.deliver!

=== Replying to emails

  reply = email.reply_to_all
  reply.body = "I'd love to go out!"
  reply.deliver!

=== Forwarding emails

  forward = email.forward
  forward.body = 'Interested?'
  forward.deliver!

=== Processing email asynchronously

In addition to delivering emails immediately, you can also *queue* emails so
that an external application processes and delivers them (as mentioned above).
This is especially useful when you want to asynchronously send e-mails so that
it doesn't block the user interface on your web application.

To process queued emails, you need an external cron job that checks and sends
them like so:

  Email.with_state('queued').each do |email|
    email.deliver!
  end

== Testing

Before you can run any tests, the following gem must be installed:
* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]

To run against a specific version of Rails:

  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails

== Dependencies

* Rails 2.1 or later
* plugins_plus[http://wiki.pluginaweek.org/Plugins_plus]
* has_messages[http://wiki.pluginaweek.org/Has_messages]
* state_machine[http://wiki.pluginaweek.org/State_machine]