I/O SMTP

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

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 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 SMTP 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
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.

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.

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

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: