mail_room is a configuration based process that will idle on IMAP connections and POST to a delivery URL whenever a new message is received on the configured mailbox and folder.

Build Status Code Climate


Add this line to your application's Gemfile:

gem 'mail_room'

And then execute:

$ bundle

Or install it yourself as:

$ gem install mail_room

You will also need to install faraday or letter_opener if you use the postback or letter_opener delivery methods, respectively.


mail_room -c /path/to/config.yml


    :email: ""
    :password: "password"
    :name: "inbox"
    :delivery_url: "http://localhost:3000/inbox"
    :delivery_token: "abcdefg"
    :email: ""
    :password: "password"
    :name: "inbox"
    :delivery_method: postback
    :delivery_url: "http://localhost:3000/inbox"
    :delivery_token: "abcdefg"
    :email: ""
    :password: "password"
    :name: "inbox"
    :delivery_method: logger
    :log_path: "/var/log/user3-email.log"
    :email: ""
    :password: "password"
    :name: "inbox"
    :delivery_method: letter_opener
    :location: "/tmp/user4-email"



Requires faraday gem be installed.

NOTE: If you're using Ruby >= 2.0, you'll need to use Faraday from >= 0.8.9. Versions before this seem to have some weird behavior with mail_room.

The default delivery method, requires delivery_url and delivery_token in configuration.

As the postback is essentially using your app as if it were an API endpoint, you may need to disable forgery protection as you would with a JSON API. In our case, the postback is plaintext, but the protection will still need to be disabled.


Configured with :delivery_method: logger.

If :log_path: is not provided, defaults to STDOUT


Configured with :delivery_method: noop.

Does nothing, like it says.


Requires letter_opener gem be installed.

Configured with :delivery_method: letter_opener.

Uses Ryan Bates' excellent letter_opener gem.

Receiving postback in Rails

If you have a controller that you're sending to, with forgery protection disabled, you can get the raw string of the email using

I would recommend having the mail gem bundled and parse the email using Mail.read_from_string(

Running in Production

I suggest running with either upstart or init.d. Check out this wiki page for some example scripts for both:


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
  6. If accepted, ask for commit rights


  1. specs, this is just a (working) proof of concept √
  2. finish code for POSTing to callback with auth √
  3. accept mailbox configuration for one account directly on the commandline; or ask for it
  4. add example rails endpoint, with auth examples
  5. add example configs for upstart/init.d √
  6. log to stdout √
  7. add a development mode that opens in letter_opener by ryanb √