Fetcher¶ ↑

Fetcher is a simple message fetcher perfect for using in a daemon or via cron.

It implements the following common pattern:

Connect to a server
Download available messages
Send each message to another object for further processing
Remove downloaded messages from the remote server

Install using:

script/plugin install git://github.com/look/fetcher.git

Dependencies¶ ↑

If you are using a 1.8 series Ruby, this plugin depends on the SystemTimer gem to work reliably. Do not forget to add it to your Gemfile or environment.rb. As Ruby 1.9 onwards use native threads SystemTimer gem becomes redundant, and timeout.rb is used instead.

Usage¶ ↑

Create a new fetcher object like the following:

@fetcher = Fetcher.create({:type => :pop,
                           :receiver => IncomingMailHandler,
                           :server => 'mail.example.com',
                           :username => 'jim',
                           :password => 'test'})

The receiver object is expected to have a receive method that takes a message as its only argument (e.g., the way ActionMailer::Base.recieve works; but you don’t have to use ActionMailer.).

Call fetch to download messages and process them.

@fetcher.fetch

Configuration¶ ↑

The following options can be passed to the Fetcher.create factory method:

type: POP or IMAP
server: The IP address or domain name of the server
port: The port to connect to (defaults to the standard port for the type of server)
ssl: Set to any value to use SSL encryption
username: The username used to connect to the server
password: The password used to connect to the server
authentication: The authentication scheme to use (IMAP only). Supports LOGIN, CRAM-MD5, and PASSWORD (defaults to PLAIN)
use_login: Set to any value to use the LOGIN command instead of AUTHENTICATE. Some servers, like GMail, do not support AUTHENTICATE (IMAP only).
sleep_time: The number of seconds to sleep between fetches (defaults to 60 seconds; valid only for the generated daemon)
in_folder: The name of the folder from which to read incoming mail (IMAP only). Defaults to INBOX.
processed_folder: The name of a folder to move mail to after it has been processed (IMAP only). NOTE: If not specified, mail is deleted.
error_folder: The name a folder to move mail that causes an error during processing (IMAP only). Defaults to bogus.

Daemon generator¶ ↑

The Fetcher plugin comes with a generator to create a daemon:

script/generate fetcher_daemon MailerDaemon

You should monitor the daemon using monit or god to ensure it does not crash.

Running via cron¶ ↑

You can also run the Fetcher periodically via cron. It is important to ensure that only one instance is running at one time, and for that the Lockfile gem is recommended.

Here is an example script to be with script/runner via cron:

begin
  Lockfile.new('cron_mail_fetcher.lock', :retries => 0) do
    config = YAML.load_file("#{RAILS_ROOT}/config/mail.yml")
    config = config[RAILS_ENV].to_options

    fetcher = Fetcher.create({:receiver => MailReceiver}.merge(config))
    fetcher.fetch
  end
rescue Lockfile::MaxTriesLockError => e
  puts "Another fetcher is already running. Exiting."
end

Extending¶ ↑

You can subclass Fetcher::Base or one of the protocol-specific classed to override the standard behavior.

Further documentation¶ ↑

<shameless-plug>

You can read more about how to use the Fetcher in the PeepCode book Receiving Email with Ruby.

</shameless-plug>

Credit & Copyright¶ ↑

Created by Dan Weinand and Luke Francl. Development supported by Slantwise Design.

Generators for Rails 3 compatibility added by Amol Hatwár, Exceed Consulting.

Licensed under the terms of the MIT License. Be excellent to each other.

mdotterer/fetcher