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(
    '[email protected]',
    '[email protected]',
    email_content
  )

  # Send an additional message through the connection. This will queue up
  # until the first has been transmitted.
  connection.send_email(
    '[email protected]',
    '[email protected]',
    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(
  '[email protected]',
  '[email protected]',
  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 © 2010 Scott Tadman, The Working Group