= remailer

Reactor-Ready Mailer Engine

== Overview

This is an EventMachine Connection implementation of a high-performance
asynchronous SMTP client. Although EventMachine ships with a built-in SMTP
client, that version is limited to sending a single email per connection,
and since establishing a connection can be the majority of the time required
to send email, this limits throughput considerably.

== Use

The Remailer system consists of the Remailer::Connection class which works
within the EventMachine environment. To use it, create a connection and then
make one or more requests to send email messages.

    EventMachine.run do
      # Establish a connection to a particular SMTP server and send debugging
      # messages to STDERR.
      connection = Remailer::Connection.open(
        'smtp.google.com',
        :debug => STDERR
      )
      
      # Send a single email message through the connection at the earliest
      # opportunity. Note that the connection will need to be fully
      # established first and this may take upwards of ten seconds.
      connection.send_email(
        'from@example.net',
        'to@example.com',
        email_content
      )

      # Send an additional message through the connection. This will queue up
      # until the first has been transmitted.
      connection.send_email(
        'from@example.net',
        'to@example.com',
        email_content
      )
      
      # Tells the connection to close out when finished.
      connection.close_when_complete!
    end

A Proc can be supplied as the :debug option to Remailer::Connection.open and
in this case it will be called with two parameters, type and message. An
example is given here where the information is simply dumped on STDOUT:

    connection = Remailer::Connection.open(
      'smtp.google.com',
      :debug => lambda { |type, message|
        puts "#{type}> #{message.inspect}"
      }
    )
    
The types defined include:

  * :send - Raw data sent by the client
  * :reply - Raw replies from the server
  * :options - The finalized options used to connect to the server

This callback procedure can be defined or replaced after the connection is
initialized:

    connection.debug do |type, message|
      STDERR.puts "%s> %s" % [ type, message.inspect ]
    end
    
It's also possible to define a handler for when the message queue has been
exhausted:

    connection.after_complete do
      STDERR.puts "Sending complete."
    end

The call to send a message can also take a callback method which must receive
one parameter that will be the numerical status code returned by the SMTP
server. Success is defined as 250, errors vary:

    connection.send_email(
      'from@example.net',
      'to@example.com',
      email_content
    ) do |status_code|
      puts "Message finished with status #{status_code}"
    end

A status code of nil is sent if the server timed out or the connection failed.

== Status

This software is currently experimental and is not recommended for production
use. Many of the internals may change significantly before a proper beta
release is made.

== Copyright

Copyright (c) 2010 Scott Tadman, The Working Group