Skip to content
Crystal library for reading and writing files in the Maildir file structure
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build status: Build Status Version License


A Crystal library for reading and writing files in the “Maildir” file and directory structure. Even though this format is mainly used for email messages, the Maildir structure and the implementation of this module are general - they do not require the file contents to be related to email.

What's so Great About the Maildir Format

See and

“Two words: no locks.” – Daniel J. Bernstein

The maildir format allows multiple processes to read and write arbitrary messages without file locks.

New messages are initially written to a “tmp/” directory with an automatically-generated unique filename. Once they are written, they are atomically moved to the “new/” directory where other processes can see and use them.

While the maildir format was created for email, it works well for arbitrary data. This library can read and write any contents using the Maildir file and directory structure. And if you want the contents to be automatically serialized/deserialized objects, pluggable serializers are supported as well.


Add the following to your application's “shard.yml”:

    github: crystallabs/
    version 5.0.1

And run “shards install”.


Initialize a Maildir and create a Maildir directory structure in “/tmp/maildir_test”:

require "maildir"
maildir ="/tmp/maildir_test") # creates tmp, new, and cur dirs
# To skip directory creation, call"/tmp/maildir_test", false)

Add a new message. This will create a new file with the contents “Hello, Crystal!” and return the path to the file. As mentioned, messages are written to the “tmp/” directory and then moved to “new/”. The path returned refers to the location in “new/”.

message = maildir.add("Hello, Crystal!")

List new messages

maildir.list("new") # => [message]

Move the message from “new” to “cur” to indicate that some process has retrieved and/or processed the message.


Indeed, the message is now in “cur/”, not “new/”.

maildir.list("new") # => []
maildir.list("cur") # => [message]

Add some flags to the message to indicate state. See “What can I put in info” at for flag conventions. The library has convenience methods like “seen!” and “seen?” for all of the 6 standard flags, but arbitrary flags can be set.

message.add_flag("S") # Mark the message as "seen"
message.add_flag("F") # Mark the message as "flagged"
message.remove_flag("F") # Unflag the message
message.add_flag("DPR") # Mark the message as "draft", "passed" and "replied"
message.remove_flag("DPR") # Remove the three flags
message.add_flag("T") # Mark the message as "trashed"
message.add_flag("X") # Mark with arbitrary-letter flag

List “cur/” messages based on flags.

 maildir.list("cur", :flags => '') # => lists all messages without any flags
 maildir.list("cur", :flags => 'F') # => lists all messages with flag 'F
 maildir.list("cur", :flags => 'FS') # => lists all messages with flag 'F' and 'S'
 maildir.list("cur", :flags => 'ST') # => lists all messages with flag 'S' and 'T'

# Flags must be specified in acending ASCII order ("ST" and not "TS").

Retrieve the key that uniquely identifies the message

key = message.key

Read/load the contents of the message

data =

Find the message based on key

message_copy = maildir.get(key)
message == message_copy # => true

Delete the message from disk

maildir.list("cur") # => []

Cleaning up Orphaned Messages

An expected (though rare) behavior is for partially-written messages to be orphaned in the “tmp/” folder (when clients fail before fully writing a message).

Find messages in “tmp/” that haven't been changed in 36 hours:


Clean them up:

maildir.get_stale_tmp.each{|msg| msg.destroy}

For more usage examples, please see files in the library's folder “spec/”.

Pluggable Serializers

By default, message data are written and read from disk as a string. However, it may be desirable to automatically process strings into useful objects. This library supports configurable serializers to convert objects to strings and back.

The following serializers are included:

  • Maildir::Serializer::Base (default - no serialization, writes and reads contents as string)

  • Maildir::Serializer::JSON (uses #to_json and JSON#parse)

  • Maildir::Serializer::YAML (uses #to_yaml and YAML#parse)

`Maildir.serializer` and `Maildir.serializer=` allow you to set default serializer.

Maildir.serializer # => (default serializer - strings)
message = maildir.add("Hello, Crystal!") # writes "Hello, Crystal!" to disk # => "Hello, Crystal!"

You can also set the serializer per individual maildir:

maildir = 'Maildir'
maildir.serializer =

And the JSON and YAML serializers work similarly, e.g.:

maildir.serializer =
my_data = {"foo" => nil, "my_array" => [1,2,3]}
message = maildir.add(my_data) # writes {"foo":null,"my_array":[1,2,3]} == my_data # => true

It is trivial to create a custom serializer. Just implement the following two methods:

dump(data, path)

Similar projects

You can’t perform that action at this time.