Fetcher¶ ↑

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

It implements the following common pattern:

1. Connect to a server

2. Download available messages

3. Send each message to another object for further processing

4. Remove downloaded messages from the remote server

Installation¶ ↑

Add this to your Gemfile:

gem 'mail-fetcher', :github => 'sofatutor/fetcher', :require => 'fetcher'

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:

rails g 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.

Added gemspec, removed legacy rails (< 3.0) support, updated readme by Martin Glaß, sofatutor.com.

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