I/O IMAP

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

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 with ring crypto (requires rustls-ring feature, enabled by default)
- Rustls with aws crypto (requires rustls-aws feature)
- Native TLS (requires native-tls feature)

[!TIP] I/O IMAP 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.

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

The whole API is documented on docs.rs, including runnable snippets for every coroutine and client.

Complete runnable programs live in ./examples; the tests also demonstrate real usage.

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

Himalaya CLI: CLI to manage emails
Himalaya TUI: TUI to manage emails
Neverest: CLI to synchronize emails
Mirador: CLI to watch mailbox changes and fire hooks on every event
Sirup: CLI to spawn pre-authenticated IMAP/SMTP sessions and expose them via Unix sockets

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

This project is licensed under either of:

at your option.

Contributions are welcome: start with CONTRIBUTING.md, which opens with the Pimalaya-wide guides to read first.

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: