# I/O IMAP [](https://docs.rs/io-imap/latest/io_imap) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya)
IMAP client library for Rust
This library is composed of 3 feature-gated layers:
- Low-level **I/O-free** coroutines: no_std-compatible state machines containing the whole IMAP logic, usable anywhere
- Mid-level **light client**: a standard, blocking client wrapping a stream you opened yourself
- High-level **full client**: the light client plus TCP connections and TLS negotiations handled for you
## Table of contents
- [Features](#features)
- [RFC coverage](#rfc-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 socket, no async runtime and no forced I/O model; run them from any blocking, async or test harness.
- **Complete IMAP4rev1 command set**: manage mailboxes, messages, flags and searches over a full standard session lifecycle.
- **Push notifications**: keep a mailbox open with IDLE and receive live change events, refreshed periodically to survive middle-boxes.
- **Incremental resync**: pull only what changed since the last sync with CONDSTORE and QRESYNC, powering the built-in mailbox watcher.
- **Server-side sorting and threading**: SORT and THREAD support, with a client-side sorting fallback for servers lacking the extension.
- **Streaming upload and download**: message bodies flow straight between the socket and your storage, never held in memory whole.
- **SASL authentication**: ANONYMOUS, LOGIN, PLAIN, XOAUTH2, OAUTHBEARER and SCRAM-SHA-256 mechanisms, with optional client identification for providers requiring it.
- **Light client**: a standard, blocking client exposing one method per IMAP command over a stream you opened yourself.
- Full standard, blocking client with **TLS** support:
- [Rustls](https://crates.io/crates/rustls) with ring crypto (requires `rustls-ring` feature, enabled by default)
- [Rustls](https://crates.io/crates/rustls) with aws crypto (requires `rustls-aws` feature)
- [Native TLS](https://crates.io/crates/native-tls) (requires `native-tls` feature)
> [!TIP]
> I/O IMAP is written in [Rust](https://www.rust-lang.org/) and uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate backend support. The default feature set is declared in [Cargo.toml](./Cargo.toml) or on [docs.rs](https://docs.rs/crate/io-imap/latest/features).
## RFC coverage
| RFC | What is covered |
|--------|--------------------------------------------------------------------------------------------------------------------------------------------|
| [2177] | IDLE: real-time mailbox change notifications pushed by the server |
| [2971] | ID: client and server identification exchange, required by some providers before authentication |
| [3501] | IMAP4rev1: greeting, capability, login and logout, mailbox listing, creation, renaming and subscription, selection and examination, fetch, store, search, copy, append, expunge, noop and STARTTLS |
| [3691] | UNSELECT: discard the selected mailbox without expunging deleted messages |
| [4315] | UIDPLUS: APPENDUID and COPYUID response codes carrying the UIDs assigned by append, copy and move |
| [4959] | SASL-IR: initial client response inline with the authentication command, saving a round-trip |
| [5161] | ENABLE: explicit activation of server capabilities |
| [5256] | SORT and THREAD: server-side message sorting and threading, with a client-side sorting fallback for servers lacking the extension |
| [6851] | MOVE: atomic message move between mailboxes |
| [7162] | CONDSTORE and QRESYNC: incremental resync through mod-sequences and vanished message reporting on select, examine and fetch |
| [7628] | OAUTHBEARER: OAuth 2.0 bearer token authentication, next to the pre-standard XOAUTH2 |
| [7677] | SCRAM-SHA-256: salted challenge-response authentication |
[2177]: https://www.rfc-editor.org/rfc/rfc2177
[2971]: https://www.rfc-editor.org/rfc/rfc2971
[3501]: https://www.rfc-editor.org/rfc/rfc3501
[3691]: https://www.rfc-editor.org/rfc/rfc3691
[4315]: https://www.rfc-editor.org/rfc/rfc4315
[4959]: https://www.rfc-editor.org/rfc/rfc4959
[5161]: https://www.rfc-editor.org/rfc/rfc5161
[5256]: https://www.rfc-editor.org/rfc/rfc5256
[6851]: https://www.rfc-editor.org/rfc/rfc6851
[7162]: https://www.rfc-editor.org/rfc/rfc7162
[7628]: https://www.rfc-editor.org/rfc/rfc7628
[7677]: https://www.rfc-editor.org/rfc/rfc7677
## Usage
The whole API is documented on [docs.rs](https://docs.rs/io-imap/latest/io_imap), including runnable snippets for every coroutine and client.
## Examples
Complete runnable programs live in [./examples](./examples); the tests also demonstrate real usage.
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
- [Mirador](https://github.com/pimalaya/mirador): CLI to watch mailbox changes and fire hooks on every event
- [Sirup](https://github.com/pimalaya/sirup): CLI to spawn pre-authenticated IMAP/SMTP sessions and expose them via Unix sockets
## 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**: 15/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)