Struct Session 

pub struct Session<State, Transport> {
    pub capabilities: Capabilities,
    /* private fields */
}

Generic session enforcing compile-time state transitions.

State is one of Unauthenticated, Authenticated, or Selected; Transport is PlainText or Tls. The type parameters gate which commands are callable — e.g. LOGIN only exists on Session<Unauthenticated, Tls>.

Fields

capabilities: Capabilities

Server capabilities known for this session, refreshed after STARTTLS and after authentication.

Implementations

impl<S, T> Session<S, T>

pub fn transition_transport<NewTransport>(self) -> Session<S, NewTransport>

Re-tag the session’s transport type parameter (e.g. PlainText → Tls after a STARTTLS upgrade). Performs no I/O.

pub fn events(&self) -> Receiver<Vec<u8>>

Subscribe to untagged server frames for this session (see RawClient::events).

pub async fn refresh_capabilities(&mut self) -> Result<(), ClientError>

Issue an explicit CAPABILITY command and update the cached set. Used after STARTTLS and after authentication when the OK response did not carry a [CAPABILITY …] response code.

impl<T> Session<Unauthenticated, T>

pub fn new(raw: RawClient, capabilities: Capabilities) -> Self

Wrap a connected RawClient as a fresh, unauthenticated session with the given initial capabilities.

impl<S, T> Session<S, T>

pub async fn logout(self) -> Result<(), ClientError>

LOGOUT is valid in any state; the session is consumed because the connection is closed afterwards.

pub async fn noop(&mut self) -> Result<(), ClientError>

NOOP keeps the connection alive and triggers status updates.

impl Session<Unauthenticated, Tls>

pub async fn login( self, user: &str, pass: Password, ) -> Result<Session<Authenticated, Tls>, ClientError>

LOGIN over TLS. The username and password are sent as IMAP quoted strings with proper escaping (", \).

Returns ClientError::CommandFailed if the credentials cannot be represented as quoted strings (8-bit, control bytes, CR, LF). Use Self::authenticate_plain in that case.

pub async fn authenticate_plain( self, user: &str, pass: &Password, ) -> Result<Session<Authenticated, Tls>, ClientError>

AUTHENTICATE PLAIN (RFC 4616). Credentials travel as base64 over the SASL exchange — no quoting limitations and 8-bit safe.

impl<T> Session<Authenticated, T>

pub async fn select( self, mailbox: &str, ) -> Result<Session<Selected, T>, ClientError>

SELECT — open a mailbox read-write and transition to Selected.

pub async fn examine( self, mailbox: &str, ) -> Result<Session<Selected, T>, ClientError>

EXAMINE — open a mailbox read-only and transition to Selected.

pub async fn list( &mut self, reference: &str, mailbox_mask: &str, ) -> Result<Vec<u8>, ClientError>

LIST — list mailboxes matching mailbox_mask under reference.

impl<T> Session<Selected, T>

pub async fn fetch_raw( &mut self, sequence_set: &str, items: &str, ) -> Result<Vec<u8>, ClientError>

FETCH returning the raw tagged-response bytes.

pub async fn fetch( &mut self, sequence_set: &str, items: &str, ) -> Result<Vec<FetchResult>, ClientError>

FETCH returning structured FetchResult entries derived from the broadcast untagged FETCH frames.

pub async fn fetch_body( &mut self, sequence_set: &str, ) -> Result<Option<String>, ClientError>

Convenience: fetch the body of the first message in sequence_set.

pub async fn search( &mut self, query: SearchQuery, ) -> Result<Vec<u32>, ClientError>

SEARCH — return the message sequence numbers matching query.

pub async fn uid_search( &mut self, query: SearchQuery, ) -> Result<Vec<u32>, ClientError>

UID SEARCH — return the message UIDs matching query.

pub async fn store( &mut self, sequence_set: &str, action: StoreAction, flags: &[Flag], ) -> Result<Vec<u8>, ClientError>

STORE — apply a flag action (add / remove / set) to the messages in sequence_set (a sequence-number set such as "1:5" or "1,3,5").

pub async fn uid_store( &mut self, uid_set: &str, action: StoreAction, flags: &[Flag], ) -> Result<Vec<u8>, ClientError>

UID STORE — like store but addressed by UID set.

pub async fn expunge(&mut self) -> Result<Vec<u8>, ClientError>

EXPUNGE — permanently remove messages flagged \Deleted from the selected mailbox.

pub async fn close_mailbox( self, ) -> Result<Session<Authenticated, T>, ClientError>

CLOSE — implicitly expunges deleted messages and transitions back to Authenticated.

pub async fn unselect(self) -> Result<Session<Authenticated, T>, ClientError>

UNSELECT (RFC 3691) — like CLOSE but without expunging. Errors if the server has not advertised the UNSELECT capability.

pub async fn check(&mut self) -> Result<(), ClientError>

CHECK — implementation-defined housekeeping checkpoint.

pub async fn idle(&mut self) -> Result<IdleHandle, ClientError>

IDLE (RFC 2177). Returns an IdleHandle; call stop() on it to gracefully terminate. Callers must re-issue IDLE at least every ~28 minutes — see crate::idle for details.

pub async fn move_messages( &mut self, sequence_set: &str, mailbox: &str, ) -> Result<Vec<u8>, ClientError>

MOVE (RFC 6851). Errors if the server has not advertised MOVE.