imap-rs 0.2.0

A high-security, memory-safe, and async-native IMAP library for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

<p align="center">
  <img src="./assets/banner.svg" alt="imap-rs — secure, async, pure-Rust IMAP" width="100%">
</p>

# imap-rs

[![CI](https://github.com/YpNo/imap-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/YpNo/imap-rs/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/imap-rs.svg)](https://crates.io/crates/imap-rs)
[![GitHub release](https://img.shields.io/github/v/release/YpNo/imap-rs?sort=semver)](https://github.com/YpNo/imap-rs/releases/latest)
[![docs.rs](https://docs.rs/imap-rs/badge.svg)](https://docs.rs/imap-rs)
[![codecov](https://codecov.io/gh/YpNo/imap-rs/branch/main/graph/badge.svg)](https://codecov.io/gh/YpNo/imap-rs)
[![MSRV](https://img.shields.io/badge/MSRV-1.95.0-blue.svg)](https://github.com/YpNo/imap-rs)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

A modern, high-performance, and security-first IMAP library for Rust.

## Project Status & Call for Maintainers

> **Heads-up:** `imap-rs` has so far been **mainly "vibe coded"** — built rapidly with heavy AI assistance rather than by a seasoned IMAP/Rust team. It compiles cleanly, is panic-free in its production paths, and ships with unit + integration tests, a parser fuzz target, CI, and security hardening (`rustls`-only TLS, `zeroize`d credentials, `#![forbid(unsafe_code)]` across all crates). However, it has **not** yet been battle-tested in production or independently audited.

I'm now looking for **Senior Rust developers** to help **maintain and steward** this project long-term — reviewing the architecture and protocol correctness, hardening edge cases, expanding IMAP4rev2 / extension coverage, and guiding releases.

If you have deep Rust and/or IMAP experience and want to get involved:

- Open or comment on a [GitHub issue](https://github.com/YpNo/imap-rs/issues), or start a [discussion](https://github.com/YpNo/imap-rs/discussions)
- Let me know you're interested in a **maintainer** role
- See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow, quality bar, and coding standards

Contributions of every size are welcome — but experienced maintainer reviews are what the project needs most right now.

## Features

- **Security First**: 100% Safe Rust. Built-in protection against credential leaks using `zeroize`.
- **Memory Safe TLS**: Exclusively uses `rustls` (no OpenSSL or Native-TLS).
- **Zero-Copy Parser**: Hand-rolled recursive descent parser for maximum performance without allocations.
- **Typed State Machine**: Leverages Rust's type system to enforce valid IMAP command sequences at compile-time.
- **IMAP4rev2 Ready**: Designed for RFC 9051 with backward compatibility via automatic capability negotiation.
- **Async Native**: Built on `tokio` for high-concurrency workloads.

## Project Structure

The project is split into three core crates to ensure a clean separation of concerns. The `imap-rs` umbrella crate re-exports all three:

- `imap-rs-core` (re-exported as `imap_rs::core`): Protocol types, AST, and the zero-copy parser (no I/O).
- `imap-rs-client` (re-exported as `imap_rs::client`): Async session management, command pipelining, and state machine.
- `imap-rs-tls` (re-exported as `imap_rs::tls`): High-level secure connection wrapper using `rustls`.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
imap-rs = "0.2"
```

### Basic Example

```rust
use imap_rs::connect_tls;
use imap_rs::credentials::Password;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // connect_tls performs TCP + TLS handshake (both with timeouts) and
    // fetches CAPABILITY in the encrypted channel.
    let session = connect_tls("imap.example.com", 993).await?;

    // LOGIN is only available on TLS sessions (compile-time enforced).
    // Username and password are quote-escaped per RFC 9051; passwords
    // containing 8-bit or control bytes should use AUTHENTICATE PLAIN
    // (`session.authenticate_plain(...)`).
    let auth = session.login("user", Password::new("pass")).await?;

    // SELECT a mailbox (transitions to Selected state).
    let mut inbox = auth.select("INBOX").await?;

    // FETCH returns structured results.
    for msg in inbox.fetch("1:*", "BODY[]").await? {
        println!("seq={} uid={:?} body={}B",
                 msg.seq, msg.uid, msg.body.as_deref().map(|b| b.len()).unwrap_or(0));
    }

    Ok(())
}
```

### STARTTLS

```rust
let session = imap_rs::connect_starttls("imap.example.com", 143).await?;
// Capabilities are *only* trusted from inside the TLS channel.
```

## Development & Testing

### Toolchain
This project is pinned to Rust **1.95.0** to ensure consistent diagnostic output for UI tests (`trybuild`). A `rust-toolchain.toml` file is included in the repository.

### Running Tests
To run all tests (including state-machine validation):
```bash
cargo test --workspace
```

### Coverage
We use `cargo-tarpaulin` for coverage. You can run it on the stable toolchain:
```bash
cargo tarpaulin --all-features --workspace --timeout 120 --out xml
```

### Troubleshooting UI Tests
If you see a `mismatch` error in `tests/ui/` after updating the compiler or changing error messages, you can "bless" the new output:
```bash
TRYBUILD=overwrite cargo test -p imap-rs-client --test type_state_tests
```
Verify the changes with `git diff` before committing.

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.

## Security

Please see [SECURITY.md](SECURITY.md) for our vulnerability disclosure policy.

## License

Licensed under the MIT license.