io-maildir 0.1.0

Maildir client library
Documentation

I/O Maildir Documentation Matrix Mastodon

Maildir client library, written in Rust

This library is composed of 2 feature-gated layers:

  • Low-level I/O-free coroutines: these no_std-compatible state machines contain the whole Maildir logic and can be used anywhere
  • Mid-level std client: a standard, blocking Maildir client built on std::fs

Table of contents

Features

  • I/O-free coroutines: no_std state machines; no filesystem calls, no async runtime, no std required, drive against any blocking, async, or fuzz harness.
  • Standard, blocking client (requires client feature) backed by std::fs.
  • Maildir delivery protocol: the entry-store coroutine writes to /tmp first, then atomically renames into /cur or /new, producing IDs of the shape secs.#counter.M<nanos>P<pid>.<host>.
  • Maildir++ mode: optional dotted folder enumeration (.Work.Foo) and inbox surfacing, gated by the maildirpp store flag.
  • Dovecot keywords resolution: read / write the dovecot-keywords slot table (a..z letters), gated by the dovecot_keywords client option.
  • Header round-trip for custom keywords: inject and strip X-Keywords / X-Label headers, gated by keywords_header and strip_headers.

[!TIP] I/O Maildir is written in Rust and uses cargo features to gate backend support. The default feature set is declared in Cargo.toml or on docs.rs.

Specification coverage

This library implements the Maildir format as I/O-agnostic coroutines.

Coroutine What it does
MaildirCreate Creates root, cur, new, tmp in lexicographic order
MaildirDelete Recursively removes a Maildir
MaildirRename Renames a Maildir within its parent directory
MaildirList Lists every valid Maildir inside a root directory
MaildirEntryStore Writes to /tmp, then atomically renames into /cur or /new with optional flags
MaildirEntryGet Locates an entry by ID and reads its contents
MaildirEntryList Scans both /new and /cur and returns every confirmed entry
MaildirEntryCopy Copies an entry between Maildirs
MaildirEntryMove Moves an entry between Maildirs
MaildirEntryLocate Finds an entry file by ID across cur, new and tmp
MaildirFlagsAdd Adds flags to an entry in /cur (no-op for /new and /tmp)
MaildirFlagsRemove Removes flags from an entry in /cur (no-op for /new and /tmp)
MaildirFlagsSet Replaces the flags of an entry in /cur (no-op for /new and /tmp)
DovecotLoad Reads the per-folder dovecot-keywords slot table
DovecotStore Writes a per-folder dovecot-keywords slot table

Usage

I/O Maildir can be consumed two ways, depending on how much of the I/O stack you want to own. Each mode is gated by cargo features.

Whichever mode you pick, every coroutine implements the MaildirCoroutine trait. Its resume(arg: Option<MaildirReply>) method returns a MaildirCoroutineState<Yield, Return> with two variants:

  • Yielded(Y): intermediate. Y is MaildirYield, mixing filesystem step requests (WantsDirCreate, WantsDirRead, WantsDirRemove, WantsDirExists, WantsFileCreate, WantsFileRead, WantsFileExists, WantsRename, WantsCopy) with the three environmental inputs used by the delivery protocol to mint entry identifiers (WantsTime, WantsPid, WantsHostname).
  • Complete(R): terminal. By convention R = Result<Output, Error> carrying the operation's final value.

The driver answers each Yielded(MaildirYield::Wants*) with the matching MaildirReply variant on the next resume.

I/O-free coroutines

No features required: works in #![no_std], no filesystem calls, no async runtime. You own the loop and the syscalls; the library only computes the operations to perform and consumes their results.

Create a fresh Maildir against a blocking caller (the same shape works under async or in-memory replay):

use std::fs;

use io_maildir::{
    coroutine::*,
    maildir::create::MaildirCreate,
    path::{FsPath, MaildirPath},
    store::MaildirStore,
};

let store = MaildirStore { root: FsPath::new("/path/to/root"), maildirpp: false };
let name = MaildirPath::from("inbox");

let mut coroutine = MaildirCreate::new(&store, name);
let mut arg: Option<MaildirReply> = None;

loop {
    match coroutine.resume(arg.take()) {
        MaildirCoroutineState::Complete(Ok(())) => break,
        MaildirCoroutineState::Complete(Err(err)) => panic!("{err}"),
        MaildirCoroutineState::Yielded(MaildirYield::WantsDirCreate(paths)) => {
            for path in paths {
                fs::create_dir_all(path.as_str()).unwrap();
            }
            arg = Some(MaildirReply::DirCreate);
        }
        MaildirCoroutineState::Yielded(other) => unreachable!("MaildirCreate yielded {other:?}"),
    }
}

Drive a multi-step command (store an entry) the same way:

use std::{
    fs, process,
    time::{SystemTime, UNIX_EPOCH},
};

use gethostname::gethostname;
use io_maildir::{
    coroutine::*,
    entry::store::{MaildirEntryStore, MaildirEntryStoreOutput},
    flag::types::MaildirFlags,
    maildir::types::{Maildir, MaildirSubdir},
    path::FsPath,
};

let maildir = Maildir::from_path(FsPath::new("/path/to/root/inbox"));
let contents = b"From: alice@example.com\r\nSubject: Hello\r\n\r\nHello!\r\n".to_vec();

let mut coroutine = MaildirEntryStore::new(maildir, MaildirSubdir::New, MaildirFlags::default(), contents);
let mut arg: Option<MaildirReply> = None;

let MaildirEntryStoreOutput { id, path } = loop {
    match coroutine.resume(arg.take()) {
        MaildirCoroutineState::Complete(Ok(out)) => break out,
        MaildirCoroutineState::Complete(Err(err)) => panic!("{err}"),
        MaildirCoroutineState::Yielded(MaildirYield::WantsTime) => {
            let ts = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
            arg = Some(MaildirReply::Time { secs: ts.as_secs(), nanos: ts.subsec_nanos() });
        }
        MaildirCoroutineState::Yielded(MaildirYield::WantsPid) => {
            arg = Some(MaildirReply::Pid(process::id()));
        }
        MaildirCoroutineState::Yielded(MaildirYield::WantsHostname) => {
            arg = Some(MaildirReply::Hostname(gethostname().into_string().unwrap_or_default()));
        }
        MaildirCoroutineState::Yielded(MaildirYield::WantsFileCreate(files)) => {
            for (path, bytes) in files {
                fs::write(path.as_str(), &bytes).unwrap();
            }
            arg = Some(MaildirReply::FileCreate);
        }
        MaildirCoroutineState::Yielded(MaildirYield::WantsRename(pairs)) => {
            for (from, to) in pairs {
                fs::rename(from.as_str(), to.as_str()).unwrap();
            }
            arg = Some(MaildirReply::Rename);
        }
        MaildirCoroutineState::Yielded(other) => unreachable!("MaildirEntryStore yielded {other:?}"),
    }
};

println!("stored {id} at {path}");

Std client

Enable the client feature (on by default). MaildirClient::new(root) wraps a filesystem root and exposes one method per coroutine; the resume loop is driven for you via MaildirClient::run and std::fs.

[dependencies]
io-maildir = "0.1.0" # client is enabled by default

use io_maildir::{
    client::{MaildirClient, MaildirClientError},
    flag::types::MaildirFlags,
    maildir::types::MaildirSubdir,
};

# fn main() -> Result<(), MaildirClientError> {
let mut client = MaildirClient::new("/path/to/root");
// client.store.maildirpp = true; // opt into Maildir++ if needed

client.create_maildir("inbox")?;
let maildir = client.load_maildir("inbox")?;

let contents = b"From: alice@example.com\r\nSubject: Hello\r\n\r\nHello!\r\n".to_vec();
let (id, path) = client.store(maildir, MaildirSubdir::New, MaildirFlags::default(), contents)?;

println!("stored {id} at {path}");
# Ok(())
# }

Logical mailbox names ("inbox", "Archive/2024") are translated to on-disk paths by client.store according to its maildirpp flag: in fs layout (default) "Archive/2024" becomes <root>/Archive/2024/; in Maildir++ it becomes <root>/.Archive.2024/.

Examples

See complete examples at ./examples.

Have also a look at real-world projects built on top of this library:

AI disclosure

This project is developed with AI assistance. This section documents how, so users and downstream packagers can make informed decisions.

  • Tools: Claude Code (Anthropic), Opus 4.7, invoked locally with a persistent project-scoped memory and a small set of repo-specific rules.

  • Used for: Refactors, mechanical multi-file edits, boilerplate (feature gates, error enums, derive macros, trait impls), test scaffolding, doc polish, exploratory design conversations.

  • Not used for: Engineering, critical code, git manipulation (commit, merge, rebase…), real-world tests.

  • Verification: Every AI-assisted change is read, compiled, tested, and formatted before commit (nix develop --command cargo check / cargo test / cargo fmt). Behavioural correctness is verified against the relevant spec, not assumed from the model output. Tests are never adjusted to fit AI-generated code; the code is adjusted to fit correct behaviour.

  • Limitations: AI models occasionally produce code that compiles and passes tests but is subtly wrong: off-by-one errors, missed edge cases, plausible but nonexistent APIs, stale spec references. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.

  • Last reviewed: 05/06/2026

License

This project is licensed under either of:

at your option.

Social

Sponsoring

nlnet

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

If you appreciate the project, feel free to donate using one of the following providers:

GitHub Ko-fi Buy Me a Coffee Liberapay thanks.dev PayPal