Clacks

"The clacks is a system of shutter semaphore towers which occupies roughly the same cultural space as telegraphy in nineteenth century Europe." ^[1]

Clacks is an easy way to process incoming emails in ruby. It uses the POP3 or IMAP protocol. If the IMAP protocol is used and the IMAP server advertises the IDLE capability it will use that. Which means that emails are pushed to your email processor instead of having to poll for it at regular intervals, which in turn means emails arrive near real-time at your systems.

Clacks can be used standalone and/or within a Rails environment.

Installation and Usage

If you use Rails, add this to your Gemfile:

gem 'clacks', :require => nil

Then create a configuration file, using ruby syntax, such as:

# Configuration of clacks
# See Clacks::Configurator for documentation on options
#
# Put this in: <RAILS_ROOT>/config/clacks.rb
#

poll_interval 30
pid "tmp/pids/clacks.pid"
stdout_path 'log/clacks.log'
stderr_path 'log/clacks.log'

imap({
  :address    => "imap.googlemail.com",
  :port       => 993,
  :user_name  => '<user_name>'
  :password   => '<password>'
  :enable_ssl => true,
})

find_options({
  :mailbox => 'INBOX',
  :archivebox => '[Gmail]/All Mail',
  :delete_after_find => true
})

on_mail do |mail|
  Clacks.logger.info "Got new mail from #{mail.from.first}, subject: #{mail.subject}"

  to = mail.to.first
  if to =~ /^task-(\d+)@example.com/
    Task.find($1).add_note(mail)
  elsif to =~ /^(\w+)@example.com/
    Account.find_by_name($1).tickets.create_from_mail!(mail)
  else
    # Prevent deletion of this mail after all
    mail.skip_deletion
  end
end

See Clacks::Configurator for documentation on all options.

Start clacks:

/project/my_rails_app$ clacks --help
/project/my_rails_app$ clacks

Clacks can run as a daemon:

/project/my_rails_app$ clacks -D

Once it's running as a daemon process you can control it via sending signals. See the available signals below.

See the contrib directory for handy init.d, logrotate and monit scripts.

Signals

• KILL - quick shutdown, kills the process immediately.

• TERM/QUIT/INT - graceful shutdown, waits for the worker process to finish processing an email.

• USR1 - reopen logs

Copyright

Copyright (c) 2013-2016 ITRP. See MIT-LICENSE for details.