# I/O m2dir [](https://docs.rs/io-m2dir/latest/io_m2dir) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya) [](https://pimalaya.org/sponsor/)
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 policy](https://github.com/pimalaya/.github/blob/master/AI_POLICY.md)
- [License](#license)
- [Social](#social)
- [Contributing](https://github.com/pimalaya/.github/blob/master/CONTRIBUTING.md)
- [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 client**: a blocking 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
See documentation at [docs.rs](https://docs.rs/io-m2dir/latest/io_m2dir).
## Examples
See complete examples at [./tests](./tests).
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
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
## 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)
## 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/)
- 2026 → 2027: [NGI Zero Commons Fund](https://nlnet.nl/project/Pimalaya-pimdir/)
This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider [sponsoring](https://pimalaya.org/sponsor/) its development:
[](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)