# I/O IMAP [](https://docs.rs/io-imap/latest/io_imap) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya) [](https://pimalaya.org/sponsor/)
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 policy](https://github.com/pimalaya/.github/blob/master/AI_POLICY.md)
- [License](#license)
- [Social](#social)
- [Contributing](./CONTRIBUTING.md)
- [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 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
See documentation at [docs.rs](https://docs.rs/io-imap/latest/io_imap).
## Examples
See complete examples at [./examples](./examples).
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
## 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)