Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
245 lines (155 sloc) 7.25 KB

Mailman User Guide

Mailman is a microframework for processing incoming email.

Here is an example Mailman app that takes incoming messages to a support email account, and adds them to a database.

# mailman_app.rb
require 'mailman'

Mailman.config.maildir = '~/Maildir' do
  to '' do

The Mailman app could then be started by running ruby mailman_app.rb.


Installation is as simple as gem install mailman.

Routes & Conditions

A Condition specifies the part of the message to match against. to, from, and subject are some valid conditions. A Matcher is used by a condition to determine whether it matches the message. Matchers can be strings or regular expressions. One or more Condition/Matcher pairs are combined with a block of code to form a Route.


There are string and regular expression matchers. Both can perform captures.


String matchers are very simple. They search through a whole field for a specific substring. For instance: 'ID' would match Ticket ID, User ID, etc.

They can also perform named captures. '' will match any email address that ends with, and store the user part of the address in a capture called username. Captures can be accessed by using the params helper inside of blocks, or with block arguments (see below for details).

The capture names may only contain letters and underscores. Behind the scenes they are compiled to regular expressions, and each capture is the equivalent to .*. There is currently no way to escape % characters. If a literal % is required, and Mailman thinks it is a named capture, use a regular expression matcher instead.

Regular expression

Regular expressions may be used as matchers. All captures will be available from the params helper (params[:captures]) as an Array, and as block arguments.


Routes are defined within a Mailman application block: do
  # routes here

Messages are passed through routes in the order they are defined in the application from top to bottom. The first matching route's block will be called.

Condition Chaining

Conditions can be chained so that the route will only be executed if all conditions pass:

to('').subject(/urgent/) do
  # process urgent message here

Special routes

The default route is a catch-all that is run if no other routes match:

default do
  # process non-matching messages

Block Arguments

All captures from matchers are available as block arguments:

from('').subject(/Ticket (\d+)/) do |username, ticket_id|
  puts "Got message from #{username} about Ticket #{ticket_id}"

Class Routing

Messages can also be routed to methods. For instance, to route to an Object with a receive instance method defined, this will work:

from '', Sample

Messages can also be routed to arbitrary instance methods:

from '', 'ExampleClass#new_message'

The method should accept two arguments, the message object, and the params:

def receive(message, params)
  # process message here

Route Helpers

There are two helpers available inside of route blocks:

The params hash holds all captures from matchers:

from('').subject(/RE: (.*)/) do
  params[:user] #=> 'chunkybacon'
  # it is an indifferent hash, so you can use strings and symbols
  # interchangeably as keys
  params['captures'][0] #=> 'A very important message about pigs'

The message helper is a Mail::Message object that contains the entire message. See the mail docs for information on the properties available.


Currently there are five conditions available: to, from, cc, subject, body

More can be added easily (see lib/mailman/route/conditions.rb).


There are currently three types of receivers in Mailman: Standard Input, Maildir, and POP3. If IMAP or any complex setups are required, use a mail retriever like getmail with the Maildir receiver.

Standard Input

If a message is piped to a Mailman app, this receiver will override any configured receivers. The app will process the message, and then quit. This receiver is useful for testing and debugging. This feature can be disabled with the Mailman.config.ignore_stdin option.

Example: cat plain_message.eml | ruby mailman_app.rb


The POP3 receiver is enabled when the Mailman.config.pop3 hash is set. It will poll every minute by default (this can be changed with Mailman.config.poll_interval). After new messages are processed, they will be deleted from the server. No copy of messages will be saved anywhere after processing. If you want to keep a copy of messages, it is recommended that you use a mail retriever with the Maildir receiver. You could also use Gmail and set it to keep messages after they have been retrieved with POP3.


The Maildir receiver is enabled when Mailman.config.maildir is set to a directory. If the cur, new, and tmp folders do not already exist in the folder, they will be created. All messages in new folder will be processed when the application launches, then moved to the cur folder, and marked as seen. After processing these messages, Mailman will use the fssm gem to monitor the new folder, and process messages as they are created.


Configuration is stored in the Mailman.config object. All paths are relative to the process's working directory or absolute if starting with a /.


Mailman.config.logger can be set to a Logger instance. You should change this if you want to log to a file in production.

Example: Mailman.config.logger ='logs/mailman.log')


POP3 Receiver

Mailman.config.pop3 stores an optional POP3 configuration hash. If it is set, Mailman will use POP3 polling as the receiver.


Mailman.config.pop3 = {
  :username => '',
  :password => 'foobar',
  :server   => '',
  :port     => 995, # defaults to 110
  :ssl      => true # defaults to false


Mailman.config.poll_interval is the duration in seconds to wait between checking for new messages on the server. It is currently only used by the POP3 reciever. If it is set to 0, Mailman will do a one-time retrieval and then exit.

Default: 60


Mailman.config.maildir is the location of a Maildir folder to watch. If it is set, Mailman will use Maildir watching as the receiver.

Example: Mailman.config.maildir = '~/Maildir'


Mailman.config.rails_root is the location of the root of a Rails app to load the environment from. If this option is set to nil, Rails environment loading will be disabled.

Default: '.'

Standard input receiver

Mailman.config.ignore_stdin disables the STDIN receiver, which can interfere with running Mailman with cron or as a daemon.

Default: false