# I/O m2dir [](https://docs.rs/io-m2dir/latest/io_m2dir) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya)
M2dir client library for Rust
This library is composed of 2 feature-gated layers:
- Low-level **I/O-free** coroutines: no_std-compatible state machines containing the whole m2dir logic, usable anywhere
- Mid-level **std client**: a standard, blocking client backed by the local filesystem
## Table of contents
- [Features](#features)
- [Specification coverage](#specification-coverage)
- [Usage](#usage)
- [Examples](#examples)
- [AI disclosure](#ai-disclosure)
- [License](#license)
- [Social](#social)
- [Contributing](#contributing)
- [Sponsoring](#sponsoring)
## Features
- **I/O-free coroutines**: state machines with no filesystem call, no async runtime and no forced I/O model; run them from any blocking, async or test harness.
- **Atomic message delivery**: a message is written to a temporary file first, then atomically renamed into place, so a reader never sees a half-written entry.
- **Sidecar flag metadata**: per-message flags live in a separate metadata file next to each entry, added, removed or replaced independently of the message itself.
- **Self-contained format primitives**: the spec's custom base64, hashing, percent-encoding and pseudo-random naming are computed in-crate, with no external base64, random or percent dependency dragged into the core.
- **Standard, blocking client**: a ready-made client backed by the local filesystem, exposing one method per coroutine, with a parallel bulk read for large mailboxes.
> [!TIP]
> I/O m2dir is written in [Rust](https://www.rust-lang.org/) and uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate the standard client. The default feature set is declared in [Cargo.toml](./Cargo.toml) or on [docs.rs](https://docs.rs/crate/io-m2dir/latest/features).
## Specification coverage
This library implements the [m2dir](https://man.sr.ht/~bitfehler/m2dir/) mail storage format as I/O-agnostic coroutines, covering the full lifecycle of a store:
| Area | What is covered |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
| Store lifecycle | Initialise a store, then create, list and remove mailbox directories, including nested ones |
| Message delivery | Write a message through the atomic temporary-file-then-rename protocol, deriving the filename from the message date, a content checksum and a random nonce |
| Message access | List every message, read one back with checksum validation, and remove it together with its metadata |
| Flags | Add, remove or replace the per-message flag set stored in the metadata sidecar, deleting the sidecar when the set becomes empty |
## Usage
The whole API is documented on [docs.rs](https://docs.rs/io-m2dir/latest/io_m2dir), including runnable snippets for every coroutine and the client.
## Examples
The tests demonstrate real usage, and each coroutine module carries a runnable snippet in its documentation.
Have also a look at real-world projects built on top of this library:
- [Himalaya CLI](https://github.com/pimalaya/himalaya): CLI to manage emails
- [Himalaya TUI](https://github.com/pimalaya/himalaya-tui): TUI to manage emails
- [Neverest](https://github.com/pimalaya/neverest): CLI to synchronize emails
## 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), 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. Behavioural correctness is verified against the relevant RFC or upstream 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. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.
- **Last reviewed**: 16/07/2026
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
at your option.
## Social
- Chat on [Matrix](https://matrix.to/#/#pimalaya:matrix.org)
- News on [Mastodon](https://fosstodon.org/@pimalaya) or [RSS](https://fosstodon.org/@pimalaya.rss)
- Mail at [pimalaya.org@posteo.net](mailto:pimalaya.org@posteo.net)
## Contributing
Contributions are welcome: start with [CONTRIBUTING.md](./CONTRIBUTING.md), which opens with the Pimalaya-wide guides to read first.
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that have been financially supporting the project for years:
- 2022 → 2023: [NGI Assure](https://nlnet.nl/project/Himalaya/)
- 2023 → 2024: [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/)
- 2024 → 2026: [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/)
- *2027 in preparation…*
If you appreciate the project, feel free to donate using one of the following providers:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)