diff --git a/src/transport/smtp/async_transport.rs b/src/transport/smtp/async_transport.rs index 55e4a25..e61aa2f 100644 --- a/src/transport/smtp/async_transport.rs +++ b/src/transport/smtp/async_transport.rs @@ -30,6 +30,30 @@ use crate::Tokio1Executor; use crate::{Envelope, Executor}; /// Asynchronously sends emails using the SMTP protocol +/// +/// `AsyncSmtpTransport` is the primary way for communicating +/// with SMTP relay servers to send email messages. It holds the +/// client connect configuration and creates new connections +/// as necessary. +/// +/// # Connection pool +/// +/// When the `pool` feature is enabled (default), `AsyncSmtpTransport` maintains a +/// connection pool to manage SMTP connections. The pool: +/// +/// - Establishes a new connection when sending a message. +/// - Recycles connections internally after a message is sent. +/// - Reuses connections for subsequent messages, reducing connection setup overhead. +/// +/// The connection pool can grow to hold multiple SMTP connections if multiple +/// emails are sent concurrently, as SMTP does not support multiplexing within a +/// single connection. +/// +/// However, **connection reuse is not possible** if the `SyncSmtpTransport` instance +/// is dropped after every email send operation. You must reuse the instance +/// of this struct for the connection pool to be of any use. +/// +/// To customize connection pool settings, use [`AsyncSmtpTransportBuilder::pool_config`]. #[cfg_attr(docsrs, doc(cfg(any(feature = "tokio1", feature = "async-std1"))))] pub struct AsyncSmtpTransport { #[cfg(feature = "pool")] diff --git a/src/transport/smtp/transport.rs b/src/transport/smtp/transport.rs index 2733e96..2e53787 100644 --- a/src/transport/smtp/transport.rs +++ b/src/transport/smtp/transport.rs @@ -11,7 +11,31 @@ use super::{ClientId, Credentials, Error, Mechanism, Response, SmtpConnection, S use super::{Tls, TlsParameters, SUBMISSIONS_PORT, SUBMISSION_PORT}; use crate::{address::Envelope, Transport}; -/// Sends emails using the SMTP protocol +/// Synchronously send emails using the SMTP protocol +/// +/// `SmtpTransport` is the primary way for communicating +/// with SMTP relay servers to send email messages. It holds the +/// client connect configuration and creates new connections +/// as necessary. +/// +/// # Connection pool +/// +/// When the `pool` feature is enabled (default), `SmtpTransport` maintains a +/// connection pool to manage SMTP connections. The pool: +/// +/// - Establishes a new connection when sending a message. +/// - Recycles connections internally after a message is sent. +/// - Reuses connections for subsequent messages, reducing connection setup overhead. +/// +/// The connection pool can grow to hold multiple SMTP connections if multiple +/// emails are sent concurrently, as SMTP does not support multiplexing within a +/// single connection. +/// +/// However, **connection reuse is not possible** if the `SmtpTransport` instance +/// is dropped after every email send operation. You must reuse the instance +/// of this struct for the connection pool to be of any use. +/// +/// To customize connection pool settings, use [`SmtpTransportBuilder::pool_config`]. #[cfg_attr(docsrs, doc(cfg(feature = "smtp-transport")))] #[derive(Clone)] pub struct SmtpTransport {