Skip to main content

rusted_mail/
lib.rs

1//! Protocol and storage engine for the Rusted Mail stack.
2//!
3//! `rusted-mail` contains the platform-independent implementation shared by
4//! the project's native integrations. It provides the protocol, persistence,
5//! synchronization, provider-discovery, and message-processing machinery for
6//! IMAP, SMTP, POP3, and JMAP mail clients. It does **not** link JNI or produce an
7//! Android shared library.
8//!
9//! # Package structure
10//!
11//! The workspace separates responsibilities into three packages:
12//!
13//! - `rusted-mail` — this protocol and storage engine;
14//! - `rusted-mail-jni` — Java Native Interface entry points and asynchronous
15//!   callback handling;
16//! - `rusted-mail-android` — the `libmail_jni.so` Android packaging layer.
17//!
18//! Applications integrating through Kotlin or Java should normally consume
19//! `rusted-mail-android`. The engine's Rust API is deliberately kept separate
20//! from Android lifecycle and ABI concerns.
21//!
22//! # Cargo features
23//!
24//! No optional integration is enabled by default.
25//!
26//! - `turso-native-sync` enables Turso's native synchronization support.
27//! - `crypto-openpgp` enables `OpenPGP` message processing.
28//! - `crypto-smime` enables S/MIME message processing.
29//!
30//! Cryptographic features add substantial dependency trees and should be
31//! enabled only when the consuming application exposes the corresponding
32//! functionality.
33//!
34//! # Quick start
35//!
36//! The typed API owns session handles and keeps the JNI-oriented JSON protocol
37//! out of application code:
38//!
39//! ```no_run
40//! use rusted_mail::{AccountConfig, Credentials, MailEngine, ServerConfig};
41//!
42//! # async fn example() -> Result<(), rusted_mail::Error> {
43//! let account = AccountConfig::builder("alice@example.com")
44//!     .credentials(Credentials::password("application-password"))
45//!     .imap(ServerConfig::tls("imap.example.com", 993))
46//!     .smtp(ServerConfig::start_tls("smtp.example.com", 587))
47//!     .build()?;
48//!
49//! let engine = MailEngine::new();
50//! let session = engine.connect_imap(account).await?;
51//! for mailbox in session.list_mailboxes().await? {
52//!     println!("{}", mailbox.name);
53//! }
54//! session.close().await?;
55//! # Ok(())
56//! # }
57//! ```
58//!
59//! # Errors
60//!
61//! Operations return [`Error`]. [`Error::public`] converts an error into the serializable
62//! [`MailError`] envelope, whose [`ErrorCode`] is stable across language
63//! boundaries.
64
65#![warn(missing_docs)]
66#![warn(rustdoc::broken_intra_doc_links)]
67#![allow(dead_code)]
68
69/// Typed, platform-independent API for mail applications.
70pub mod api;
71#[doc(hidden)]
72pub mod app_logger;
73mod crypto;
74mod dns_config;
75/// Stable error codes and error envelopes shared across integration layers.
76pub mod error;
77#[allow(dead_code)]
78mod internal_imap;
79#[allow(dead_code)]
80mod internal_jmap_client;
81#[doc(hidden)]
82pub mod jmap;
83mod local_store;
84mod mail;
85#[doc(hidden)]
86pub mod models;
87mod network_security;
88#[doc(hidden)]
89pub mod oauth_provider;
90mod pop3;
91#[doc(hidden)]
92pub mod provider_autodiscovery;
93#[doc(hidden)]
94pub mod provider_presets;
95#[doc(hidden)]
96pub mod request_limits;
97#[doc(hidden)]
98pub mod runtime;
99#[doc(hidden)]
100pub mod session;
101mod turso_cloud;
102
103pub use api::{
104    AccountConfig, AccountConfigBuilder, Attachment, BodyOptions, Credentials, FetchOptions,
105    ImapSession, JmapAccountConfig, JmapAccountConfigBuilder, JmapEmail, JmapEmailQuery,
106    JmapMailbox, JmapSession, MailEngine, MailEngineBuilder, MailboxInfo, MailboxStats, Message,
107    MessageBody, MessageBuilder, MessageSet, MessageSummary, Pop3AccountConfig,
108    Pop3AccountConfigBuilder, Pop3Capabilities, Pop3MailboxStatus, Pop3Message, Pop3MessageInfo,
109    Pop3ServerConfig, Pop3Session, Pop3TlsMode, ProviderDiscovery, ProviderDiscoverySource,
110    SearchOptions, SendResult, ServerConfig, SpecialFolders, TlsMode,
111};
112#[doc(hidden)]
113pub use error::MailJniError;
114pub use error::{Error, ErrorCode, MailError};
115
116#[cfg(test)]
117pub(crate) mod test_support {
118    use std::sync::{Mutex, MutexGuard, OnceLock};
119
120    pub(crate) fn global_state_test_guard() -> MutexGuard<'static, ()> {
121        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
122        LOCK.get_or_init(|| Mutex::new(()))
123            .lock()
124            .unwrap_or_else(std::sync::PoisonError::into_inner)
125    }
126}
127
128#[cfg(test)]
129mod tests;