Crate imap_patch_for_async_imap_lite

This crate lets you connect to and interact with servers that implement the IMAP protocol (RFC 3501 and various extensions). After authenticating with the server, IMAP lets you list, fetch, and search for e-mails, as well as monitor mailboxes for changes. It supports at least the latest three stable Rust releases (possibly even older ones; check the CI results).

To connect, use the connect function. This gives you an unauthenticated Client. You can then use Client::login or Client::authenticate to perform username/password or challenge/response authentication respectively. This in turn gives you an authenticated Session, which lets you access the mailboxes at the server.

The documentation within this crate borrows heavily from the various RFCs, but should not be considered a complete reference. If anything is unclear, follow the links to the RFCs embedded in the documentation for the various types and methods and read the raw text there!

Below is a basic client example. See the examples/ directory for more.

extern crate imap;
extern crate native_tls;

fn fetch_inbox_top() -> imap::error::Result<Option<String>> {
    let domain = "imap.example.com";
    let tls = native_tls::TlsConnector::builder().build().unwrap();

    // we pass in the domain twice to check that the server's TLS
    // certificate is valid for the domain we're connecting to.
    let client = imap::connect((domain, 993), domain, &tls).unwrap();

    // the client we have here is unauthenticated.
    // to do anything useful with the e-mails, we need to log in
    let mut imap_session = client
        .login("me@example.com", "password")
        .map_err(|e| e.0)?;

    // we want to fetch the first email in the INBOX mailbox
    imap_session.select("INBOX")?;

    // fetch message number 1 in this mailbox, along with its RFC822 field.
    // RFC 822 dictates the format of the body of e-mails
    let messages = imap_session.fetch("1", "RFC822")?;
    let message = if let Some(m) = messages.iter().next() {
        m
    } else {
        return Ok(None);
    };

    // extract the message's body
    let body = message.body().expect("message did not have a body!");
    let body = std::str::from_utf8(body)
        .expect("message was not valid utf-8")
        .to_string();

    // be nice to the server and log out
    imap_session.logout()?;

    Ok(Some(body))
}

Opting out of native_tls

For situations where using openssl becomes problematic, you can disable the default feature which provides integration with the native_tls crate. One major reason you might want to do this is cross-compiling. To opt out of native_tls, add this to your Cargo.toml file:

[dependencies.imap]
version = "<some version>"
default-features = false

Even without native_tls, you can still use TLS by leveraging the pure Rust rustls crate. See the example/rustls.rs file for a working example.

Re-exports

pub use error::Error;

pub use error::Result;

Modules

error	IMAP error types.
extensions	Implementations of various IMAP extensions.
parse	PATCH_FOR_ASYNC_IMAP_LITE [pub]
types	This module contains types used throughout the IMAP protocol.

Structs

Client	An (unauthenticated) handle to talk to an IMAP server. This is what you get when first connecting. A succesfull call to Client::login or Client::authenticate will return a Session instance that provides the usual IMAP methods.
Session	An authenticated IMAP session providing the usual IMAP commands. This type is what you get from a succesful login attempt.

Traits

Authenticator

This trait allows for pluggable authentication schemes. It is used by Client::authenticate to authenticate using SASL.

Functions

connect	Connect to a server using a TLS-encrypted connection.
connect_starttls	Connect to a server and upgrade to a TLS-encrypted connection.
validate_str	PATCH_FOR_ASYNC_IMAP_LITE [pub]