# I/O SMTP [](https://docs.rs/io-smtp/latest/io_smtp) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya)
SMTP 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 SMTP 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: no_std state machines; no sockets, no async runtime, run them from any blocking, async or fuzz harness.
- **Message submission**: greeting, capability discovery, sender and recipient declaration, message data with automatic dot-stuffing, session reset and teardown, plus an all-in-one send.
- **STARTTLS**: upgrade a plain connection to an encrypted one, detecting bytes injected before the handshake.
- **Authentication**: the PLAIN, LOGIN, ANONYMOUS, XOAUTH2, OAUTHBEARER and SCRAM-SHA-256 mechanisms, with or without inline initial response.
- **Delivery status notifications**: ask the server to report successful, failed or delayed delivery, per recipient.
- **Server limits and diagnostics**: declared maximum message size and enhanced status codes.
- Light standard, blocking client wrapping a stream you opened and secured 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 SMTP 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-smtp/latest/features).
## RFC coverage
| RFC | What is covered |
|--------|----------------------------------------------------------------------------------------------------------|
| [5321] | SMTP itself: greeting, hello handshakes, sender and recipient declaration, message data, reset, keep-alive and quit |
| [1870] | Message size declaration: read the maximum message size the server accepts |
| [3207] | STARTTLS: upgrade a plain connection to TLS, refusing upgrades preceded by injected bytes |
| [3461] | Delivery status notifications: the notify, return, envelope and original-recipient submission parameters |
| [3463] | Enhanced status codes: the refined three-part codes some servers attach to their replies |
| [4954] | The authentication extension: the exchange wrapping every mechanism, with optional inline initial response |
| [4505] | The ANONYMOUS authentication mechanism |
| [4616] | The PLAIN authentication mechanism |
| [7628] | The OAUTHBEARER authentication mechanism, signing in with an OAuth 2.0 bearer token |
| [7677] | The SCRAM-SHA-256 authentication mechanism, verifying the server signature against replay |
The LOGIN and XOAUTH2 mechanisms have no RFC: they follow the historical draft and the Google specification respectively.
[1870]: https://www.rfc-editor.org/rfc/rfc1870
[3207]: https://www.rfc-editor.org/rfc/rfc3207
[3461]: https://www.rfc-editor.org/rfc/rfc3461
[3463]: https://www.rfc-editor.org/rfc/rfc3463
[4505]: https://www.rfc-editor.org/rfc/rfc4505
[4616]: https://www.rfc-editor.org/rfc/rfc4616
[4954]: https://www.rfc-editor.org/rfc/rfc4954
[5321]: https://www.rfc-editor.org/rfc/rfc5321
[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-smtp/latest/io_smtp), including runnable snippets for every coroutine and client.
## Examples
Complete runnable programs live in [./examples](./examples); the tests also demonstrate real usage.
## 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**: 03/06/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)