117 lines
5.1 KiB
Markdown
117 lines
5.1 KiB
Markdown
<!-- this file uses https://github.com/livioribeiro/cargo-readme -->
|
|
<!-- do not manually edit README.md, instead edit README.tpl or src/lib.rs -->
|
|
|
|
# imap
|
|
|
|
[](https://crates.io/crates/imap)
|
|
[](https://docs.rs/imap/)
|
|
[](https://crates.io/crates/imap)
|
|
[](https://dev.azure.com/jonhoo/jonhoo/_build/latest?definitionId=11&branchName=master)
|
|
[](https://cirrus-ci.com/github/jonhoo/rust-imap)
|
|
[](https://codecov.io/gh/jonhoo/rust-imap)
|
|
[](https://deps.rs/repo/github/jonhoo/rust-imap)
|
|
|
|
This crate lets you connect to and interact with servers that implement the IMAP protocol ([RFC
|
|
3501](https://tools.ietf.org/html/rfc3501) 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](https://dev.azure.com/jonhoo/jonhoo/_build/latest?definitionId=11&branchName=master)).
|
|
|
|
**This crate is looking for maintainers — reach out to [@jonhoo] if you're interested.**
|
|
|
|
[@jonhoo]: https://thesquareplanet.com/
|
|
|
|
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.
|
|
|
|
```rust
|
|
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:
|
|
|
|
```toml
|
|
[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.
|
|
|
|
## Running the test suite
|
|
|
|
To run the integration tests, you need to have [GreenMail
|
|
running](http://www.icegreen.com/greenmail/#deploy_docker_standalone). The
|
|
easiest way to do that is with Docker:
|
|
|
|
```console
|
|
$ docker pull greenmail/standalone:1.6.3
|
|
$ docker run -t -i -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.3
|
|
```
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
|
|
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
|
|
at your option.
|
|
|
|
## Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
for inclusion in the work by you, as defined in the Apache-2.0 license, shall
|
|
be dual licensed as above, without any additional terms or conditions.
|