async_imap/lib.rs
1//! # Async IMAP
2//!
3//! This crate lets you connect to and interact with servers
4//! that implement the IMAP protocol ([RFC 3501](https://tools.ietf.org/html/rfc3501) and extensions).
5//! After authenticating with the server,
6//! IMAP lets you list, fetch, and search for e-mails,
7//! as well as monitor mailboxes for changes.
8//!
9//! ## Connecting
10//!
11//! Connect to the server, for example using TLS connection on port 993
12//! or plain TCP connection on port 143 if you plan to use STARTTLS.
13//! can be used.
14//! Pass the stream to [`Client::new()`].
15//! This gives you an unauthenticated [`Client`].
16//!
17//! Then read the server greeting:
18//! ```ignore
19//! let _greeting = client
20//! .read_response().await?
21//! .expect("unexpected end of stream, expected greeting");
22//! ```
23//!
24//! ## STARTTLS
25//!
26//! If you connected on a non-TLS port, upgrade the connection using STARTTLS:
27//! ```ignore
28//! client.run_command_and_check_ok("STARTTLS", None).await?;
29//! let stream = client.into_inner();
30//! ```
31//! Convert this stream into a TLS stream using a library
32//! such as [`async-native-tls`](https://crates.io/crates/async-native-tls)
33//! or [Rustls](`https://crates.io/crates/rustls`).
34//! Once you have a TLS stream, wrap it back into a [`Client`]:
35//! ```ignore
36//! let client = Client::new(tls_stream);
37//! ```
38//! Note that there is no server greeting after STARTTLS.
39//!
40//! ## Authentication and session usage
41//!
42//! Once you have an established connection,
43//! authenticate using [`Client::login`] or [`Client::authenticate`]
44//! to perform username/password or challenge/response authentication respectively.
45//! This in turn gives you an authenticated
46//! [`Session`], which lets you access the mailboxes at the server.
47//! For example:
48//! ```ignore
49//! let mut session = client
50//! .login("alice@example.org", "password").await
51//! .map_err(|(err, _client)| err)?;
52//! session.select("INBOX").await?;
53//!
54//! // Fetch message number 1 in this mailbox, along with its RFC 822 field.
55//! // RFC 822 dictates the format of the body of e-mails.
56//! let messages_stream = imap_session.fetch("1", "RFC822").await?;
57//! let messages: Vec<_> = messages_stream.try_collect().await?;
58//! let message = messages.first().expect("found no messages in the INBOX");
59//!
60//! // Extract the message body.
61//! let body = message.body().expect("message did not have a body!");
62//! let body = std::str::from_utf8(body)
63//! .expect("message was not valid utf-8")
64//! .to_string();
65//!
66//! session.logout().await?;
67//! ```
68//!
69//! The documentation within this crate borrows heavily from the various RFCs,
70//! but should not be considered a complete reference.
71//! If anything is unclear,
72//! follow the links to the RFCs embedded in the documentation
73//! for the various types and methods and read the raw text there!
74//!
75//! See the `examples/` directory for usage examples.
76#![warn(missing_docs)]
77#![deny(rust_2018_idioms, unsafe_code)]
78
79#[cfg(not(any(feature = "runtime-tokio", feature = "runtime-async-std")))]
80compile_error!("one of 'runtime-async-std' or 'runtime-tokio' features must be enabled");
81
82#[cfg(all(feature = "runtime-tokio", feature = "runtime-async-std"))]
83compile_error!("only one of 'runtime-async-std' or 'runtime-tokio' features must be enabled");
84#[macro_use]
85extern crate pin_utils;
86
87// Reexport imap_proto for easier access.
88pub use imap_proto;
89
90mod authenticator;
91mod client;
92pub mod error;
93pub mod extensions;
94mod imap_stream;
95mod parse;
96pub mod types;
97
98#[cfg(feature = "compress")]
99pub use crate::extensions::compress::DeflateStream;
100
101pub use crate::authenticator::Authenticator;
102pub use crate::client::*;
103
104#[cfg(test)]
105mod mock_stream;