Repository files navigation

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

This crate is looking for maintainers — reach out to@jonhoo if you're interested.

To connect, use the [ClientBuilder]. This gives you an unauthenticated [Client]. You canthen use [Client::login] or [Client::authenticate] to perform username/password orchallenge/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 beconsidered a complete reference. If anything is unclear, follow the links to the RFCs embeddedin the documentation for the various types and methods and read the raw text there!

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

fnfetch_inbox_top() -> imap::error::Result<Option<String>>{let client = imap::ClientBuilder::new("imap.example.com",993).connect()?;// the client we have here is unauthenticated.// to do anything useful with the e-mails, we need to log inletmut 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-mailslet messages = imap_session.fetch("1","RFC822")?;let message =ifletSome(m) = messages.iter().next(){        m}else{returnOk(None);};// extract the message's bodylet 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))}

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

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

Even withoutnative_tls, you can still use TLS by leveraging the pure Rustrustlscrate, which is enabled with therustls-tls feature. See the example/rustls.rs filefor a working example.

To run the integration tests, you need to haveGreenMailrunning. Theeasiest way to do that is with Docker:

$docker pull greenmail/standalone:1.6.15$docker run -it --rm -e GREENMAIL_OPTS='-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.auth.disabled -Dgreenmail.verbose' -p 3025:3025 -p 3110:3110 -p 3143:3143 -p 3465:3465 -p 3993:3993 -p 3995:3995 greenmail/standalone:1.6.15

Another alternative is to test against cyrus imapd which is a more complete IMAP implementation that greenmail (supporting quotas and ACLs).

$ docker pull outoforder/cyrus-imapd-tester$ docker run -it --rm -p 3025:25 -p 3110:110 -p 3143:143 -p 3465:465 -p 3993:993 outoforder/cyrus-imapd-tester:latest

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)at your option.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shallbe dual licensed as above, without any additional terms or conditions.