This crate provides a complete set of well-designed, misuse-resistant types for the [IMAP4rev1] protocol and various [extensions]. Notably, it does not provide parsers, nor serializers, but tries to become the "standard library" for IMAP in Rust that is useful for a broad range of crates.
If you are looking for a complete codec implementation, i.e., parsers, serializers, and network support, head over to [imap-codec].
To ensure correctness, imap-types makes use of types such as
AString,
Atom,
IString,
Quoted, and
Literal.
When constructing messages, imap-types can automatically choose the best representation.
However, it's always possible to manually choose a specific representation.
Automatic Construction
This ...
rust
Command::new(
"A1",
CommandBody::login("alice", "password").unwrap(),
).unwrap();
... will produce ...
imap
A1 LOGIN alice password
However, ...
rust
Command::new(
"A1",
CommandBody::login("alice\"", b"\xCA\xFE".as_ref()).unwrap(),
)
.unwrap();
... will produce ...
imap
A1 LOGIN "alice\"" {2}
\xCA\xFE
Also, the construction ...
rust
Command::new(
"A1",
CommandBody::login("alice\x00", "password").unwrap(),
).unwrap();
... will fail because IMAP doesn't allow NULL bytes in the username (nor password).
Manual Construction
You can also use ...
rust
Command::new(
"A1",
CommandBody::login(Literal::try_from("alice").unwrap(), "password").unwrap(),
)
.unwrap();
... to produce ...
imap
A1 LOGIN {5}
alice password
... even though "alice" could be encoded more simply with an atom or quoted string.
Also, you can use Rust literals and resort to unvalidated constructors when you are certain that your input is correct:
```rust // This could be provided by the email application. let tag = TagGenerator::random();
Command { tag, body: CommandBody::Login { // Note that the "unvalidated" feature must be activated. username: AString::from(Atom::unvalidated("alice")), password: Secret::new(AString::from(Atom::unvalidated("password"))), }, }; ```
In this case, imap-codec won't stand in your way. However, it won't guarantee that you produce correct messages, either.
This crate is dual-licensed under Apache 2.0 and MIT terms.