imap_patch_for_async_imap_lite/
lib.rs

1//! This crate lets you connect to and interact with servers that implement the IMAP protocol ([RFC
2//! 3501](https://tools.ietf.org/html/rfc3501) and various extensions). After authenticating with
3//! the server, IMAP lets you list, fetch, and search for e-mails, as well as monitor mailboxes for
4//! changes. It supports at least the latest three stable Rust releases (possibly even older ones;
5//! check the [CI results](https://travis-ci.com/jonhoo/rust-imap)).
6//!
7//! To connect, use the [`connect`] function. This gives you an unauthenticated [`Client`]. You can
8//! then use [`Client::login`] or [`Client::authenticate`] to perform username/password or
9//! challenge/response authentication respectively. This in turn gives you an authenticated
10//! [`Session`], which lets you access the mailboxes at the server.
11//!
12//! The documentation within this crate borrows heavily from the various RFCs, but should not be
13//! considered a complete reference. If anything is unclear, follow the links to the RFCs embedded
14//! in the documentation for the various types and methods and read the raw text there!
15//!
16//! Below is a basic client example. See the `examples/` directory for more.
17//!
18//! ```no_run
19//! extern crate imap;
20//! extern crate native_tls;
21//!
22//! fn fetch_inbox_top() -> imap::error::Result<Option<String>> {
23//!     let domain = "imap.example.com";
24//!     let tls = native_tls::TlsConnector::builder().build().unwrap();
25//!
26//!     // we pass in the domain twice to check that the server's TLS
27//!     // certificate is valid for the domain we're connecting to.
28//!     let client = imap::connect((domain, 993), domain, &tls).unwrap();
29//!
30//!     // the client we have here is unauthenticated.
31//!     // to do anything useful with the e-mails, we need to log in
32//!     let mut imap_session = client
33//!         .login("me@example.com", "password")
34//!         .map_err(|e| e.0)?;
35//!
36//!     // we want to fetch the first email in the INBOX mailbox
37//!     imap_session.select("INBOX")?;
38//!
39//!     // fetch message number 1 in this mailbox, along with its RFC822 field.
40//!     // RFC 822 dictates the format of the body of e-mails
41//!     let messages = imap_session.fetch("1", "RFC822")?;
42//!     let message = if let Some(m) = messages.iter().next() {
43//!         m
44//!     } else {
45//!         return Ok(None);
46//!     };
47//!
48//!     // extract the message's body
49//!     let body = message.body().expect("message did not have a body!");
50//!     let body = std::str::from_utf8(body)
51//!         .expect("message was not valid utf-8")
52//!         .to_string();
53//!
54//!     // be nice to the server and log out
55//!     imap_session.logout()?;
56//!
57//!     Ok(Some(body))
58//! }
59//! ```
60//!
61//! ## Opting out of `native_tls`
62//!
63//! For situations where using openssl becomes problematic, you can disable the
64//! default feature which provides integration with the `native_tls` crate. One major
65//! reason you might want to do this is cross-compiling. To opt out of native_tls, add
66//! this to your Cargo.toml file:
67//!
68//! ```toml
69//! [dependencies.imap]
70//! version = "<some version>"
71//! default-features = false
72//! ```
73//!
74//! Even without `native_tls`, you can still use TLS by leveraging the pure Rust `rustls`
75//! crate. See the example/rustls.rs file for a working example.
76#![deny(missing_docs)]
77#![warn(rust_2018_idioms)]
78
79/// PATCH_FOR_ASYNC_IMAP_LITE [pub]
80pub mod parse;
81
82pub mod types;
83
84mod authenticator;
85pub use crate::authenticator::Authenticator;
86
87mod client;
88pub use crate::client::*;
89
90pub mod error;
91pub use error::{Error, Result};
92
93pub mod extensions;
94
95#[cfg(test)]
96mod mock_stream;
imap_patch_for_async_imap_lite/lib.rs

imap_patch_for_async_imap_lite/
lib.rs
