Struct SmtpTransport

pub struct SmtpTransport { /* private fields */ }

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.

Implementations

impl SmtpTransport

pub fn relay(relay: &str) -> Result<SmtpTransportBuilder, Error>

Simple and secure transport, using TLS connections to communicate with the SMTP server

The right option for most SMTP servers.

Creates an encrypted transport over submissions port, using the provided domain to validate TLS certificates.

pub fn starttls_relay(relay: &str) -> Result<SmtpTransportBuilder, Error>

Simple and secure transport, using STARTTLS to obtain encrypted connections

Alternative to SmtpTransport::relay, for SMTP servers that don’t take SMTPS connections.

Creates an encrypted transport over submissions port, by first connecting using an unencrypted connection and then upgrading it with STARTTLS. The provided domain is used to validate TLS certificates.

An error is returned if the connection can’t be upgraded. No credentials or emails will be sent to the server, protecting from downgrade attacks.

pub fn unencrypted_localhost() -> SmtpTransport

Creates a new local SMTP client to port 25

Shortcut for local unencrypted relay (typical local email daemon that will handle relaying)

pub fn builder_dangerous<T: Into<String>>(server: T) -> SmtpTransportBuilder

Creates a new SMTP client

Defaults are:

• No authentication
• No TLS
• A 60-seconds timeout for smtp commands
• Port 25

Consider using SmtpTransport::relay or SmtpTransport::starttls_relay instead, if possible.

pub fn from_url(connection_url: &str) -> Result<SmtpTransportBuilder, Error>

Creates a SmtpTransportBuilder from a connection URL

The protocol, credentials, host, port and EHLO name can be provided in a single URL. This may be simpler than having to configure SMTP through multiple configuration parameters and then having to pass those options to lettre.

The URL is created in the following way: scheme://user:pass@hostname:port/ehlo-name?tls=TLS.

user (Username) and pass (Password) are optional in case the SMTP relay doesn’t require authentication. When port is not configured it is automatically determined based on the scheme. ehlo-name optionally overwrites the hostname sent for the EHLO command. TLS controls whether STARTTLS is simply enabled (opportunistic - not enough to prevent man-in-the-middle attacks) or required (require the server to upgrade the connection to STARTTLS, otherwise fail on suspicion of main-in-the-middle attempt).

Use the following table to construct your SMTP url:

scheme	tls query parameter	example	default port	remarks
smtps	unset	smtps://user:pass@hostname:port	465	SMTP over TLS, recommended method
smtp	required	smtp://user:pass@hostname:port?tls=required	587	SMTP with STARTTLS required, when SMTP over TLS is not available
smtp	opportunistic	smtp://user:pass@hostname:port?tls=opportunistic	587	SMTP with optionally STARTTLS when supported by the server. Not suitable for production use: vulnerable to a man-in-the-middle attack
smtp	unset	smtp://user:pass@hostname:port	587	Always unencrypted SMTP. Not suitable for production use: sends all data unencrypted

IMPORTANT: some parameters like user and pass cannot simply be concatenated to construct the final URL because special characters contained within the parameter may confuse the URL decoder. Manually URL encode the parameters before concatenating them or use a proper URL encoder, like the following cargo script:

#!/usr/bin/env cargo

//! ```cargo
//! [dependencies]
//! url = "2"
//! ```

use url::Url;

fn main() {
    // don't touch this line
    let mut url = Url::parse("foo://bar").unwrap();

    // configure the scheme (`smtp` or `smtps`) here.
    url.set_scheme("smtps").unwrap();
    // configure the username and password.
    // remove the following two lines if unauthenticated.
    url.set_username("username").unwrap();
    url.set_password(Some("password")).unwrap();
    // configure the hostname
    url.set_host(Some("smtp.example.com")).unwrap();
    // configure the port - only necessary if using a non-default port
    url.set_port(Some(465)).unwrap();
    // configure the EHLO name
    url.set_path("ehlo-name");

    println!("{url}");
}

The connection URL can then be used in the following way:

use lettre::{
    message::header::ContentType, transport::smtp::authentication::Credentials, Message,
    SmtpTransport, Transport,
};

let email = Message::builder()
    .from("NoBody <nobody@domain.tld>".parse().unwrap())
    .reply_to("Yuin <yuin@domain.tld>".parse().unwrap())
    .to("Hei <hei@domain.tld>".parse().unwrap())
    .subject("Happy new year")
    .header(ContentType::TEXT_PLAIN)
    .body(String::from("Be happy!"))
    .unwrap();

// Open a remote connection to example
let mailer = SmtpTransport::from_url("smtps://username:password@smtp.example.com")?.build();

// Send the email
mailer.send(&email)?;

pub fn test_connection(&self) -> Result<bool, Error>

Tests the SMTP connection

test_connection() tests the connection by using the SMTP NOOP command. The connection is closed afterward if a connection pool is not used.

Trait Implementations

impl Clone for SmtpTransport

fn clone(&self) -> SmtpTransport

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SmtpTransport

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Transport for SmtpTransport

fn send_raw( &self, envelope: &Envelope, email: &[u8], ) -> Result<Self::Ok, Self::Error>

Sends an email

type Ok = Response

Response produced by the Transport

type Error = Error

Error produced by the Transport

fn send(&self, message: &Message) -> Result<Self::Ok, Self::Error>

Sends the email