Skip to content
A simple queue using the maildir format
Find file
Latest commit f854075 Feb 28, 2012 @ktheory Add travis CI build status



A wrapper for the maildir library with a queue-like interface (push and shift).

Also, a simple HTTP/JSON interface.


gem install maildir-queue


Create a queue in /home/aaron/queue

require 'maildir/queue'
queue ="/home/aaron/queue")

Push a new message onto the queue.

message = queue.push("Hello World!")

List new messages

queue.list(:new) # => [message]

List messages that are being processed

queue.list(:cur) # => []

Move the first new message to 'cur' for processing

message = queue.shift # Returns nil if no new messages # => 'Hello World!'

queue.list(:new) # => []
queue.list(:cur) # => [message]

Delete a message after it's processed


queue.list(:cur) # => []

Dealing with stalled messages

An exepected (but rare) behavior is for a client to fail while processing a message. Such messages will stay in 'cur' until retried.

Get a list of messages in cur that have not been modified in 5 minutes

messages = queue.stalled_messages( - 300)

Requeue them

count = queue.requeue_stalled_messages( - 300)

Clients can update a message's timestamps to indicate it's still being processed. Then the retry interval can be shorter than the time it takes to process a message.


Maildir::WebQueue, the HTTP/JSON interface

maildir-queue includes a simple Sinatra app providing an HTTP/JSON interface to a queue.

Configure it like so:

require 'maildir/web_queue'
app = Maildir::WebQueue
app.path = '/home/aaron/queue'

Push a message

POST /message?data=Hello World!

Shift a message

GET /message

{"key": "cur/message_id", "data": "Hello world!"}
Or 404 Not Found if no new messages

Delete a message

DELETE /message/key

Update a message's timestamps

POST /touch/key

Show count of messages in new and cur

GET /status
{"new": 2, "cur": 10}

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2010 Aaron Suggs. See LICENSE for details.

Something went wrong with that request. Please try again.