Crate async_imap

source ·
Expand description

§Async IMAP

This crate lets you connect to and interact with servers that implement the IMAP protocol (RFC 3501 and extensions). After authenticating with the server, IMAP lets you list, fetch, and search for e-mails, as well as monitor mailboxes for changes.

§Connecting

Connect to the server, for example using TLS connection on port 993 or plain TCP connection on port 143 if you plan to use STARTTLS. can be used. Pass the stream to Client::new(). This gives you an unauthenticated Client.

Then read the server greeting:

ⓘ
let _greeting = client
    .read_response().await?
    .expect("unexpected end of stream, expected greeting");

§STARTTLS

If you connected on a non-TLS port, upgrade the connection using STARTTLS:

ⓘ
client.run_command_and_check_ok("STARTTLS", None).await?;
let stream = client.into_inner();

Convert this stream into a TLS stream using a library such as async-native-tls or Rustls. Once you have a TLS stream, wrap it back into a Client:

ⓘ
let client = Client::new(tls_stream);

Note that there is no server greeting after STARTTLS.

§Authentication and session usage

Once you have an established connection, authenticate using 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. For example:

ⓘ
let mut session = client
    .login("alice@example.org", "password").await
    .map_err(|(err, _client)| err)?;
session.select("INBOX").await?;

// Fetch message number 1 in this mailbox, along with its RFC 822 field.
// RFC 822 dictates the format of the body of e-mails.
let messages_stream = imap_session.fetch("1", "RFC822").await?;
let messages: Vec<_> = messages_stream.try_collect().await?;
let message = messages.first().expect("found no messages in the INBOX");

// Extract the message 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();

session.logout().await?;

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!

See the examples/ directory for usage examples.

Re-exports§

Modules§

  • error
    IMAP error types.
  • extensions
    Implementations of various IMAP extensions.
  • 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.
  • Connection
    The underlying primitives type. Both Client(unauthenticated) and Session(after succesful login) use a Connection internally for the TCP stream primitives.
  • Session
    An authenticated IMAP session providing the usual IMAP commands. This type is what you get from a succesful login attempt.

Traits§