Crate lettre

Expand description

Lettre is an email library that allows creating and sending messages. It provides:

An easy to use email builder
Pluggable email transports
Unicode support
Secure defaults
Async support

Lettre requires Rust 1.74 or newer.

§Features

This section lists each lettre feature and briefly explains it. More info about each module can be found in the corresponding module page.

Features with 📫 near them are enabled by default.

§Typed message builder

Strongly typed message builder

builder 📫: Enable the Message builder
hostname 📫: Try to use the actual system hostname in the Message-ID header

§SMTP transport

Send emails using SMTP

smtp-transport 📫: Enable the SMTP transport
pool 📫: Connection pool for SMTP transport
hostname 📫: Try to use the actual system hostname for the SMTP CLIENTID

§SMTP over TLS via the native-tls crate

Secure SMTP connections using TLS from the native-tls crate

Uses schannel on Windows, Security-Framework on macOS, and OpenSSL on all other platforms.

native-tls 📫: TLS support for the synchronous version of the API
tokio1-native-tls: TLS support for the tokio1 async version of the API

NOTE: native-tls isn’t supported with async-std

§Building lettre with OpenSSL

When building lettre with native-tls on a system that makes use of OpenSSL, the following packages will need to be installed in order for the build and the compiled program to run properly.

Distro	Build-time packages	Runtime packages
Debian	`pkg-config`, `libssl-dev`	`libssl3`, `ca-certificates`
Alpine Linux	`pkgconf`, `openssl-dev`	`libssl3`, `ca-certificates`

§SMTP over TLS via the boring crate (Boring TLS)

Secure SMTP connections using TLS from the boring-tls crate

boring-tls: TLS support for the synchronous version of the API
tokio1-boring-tls: TLS support for the tokio1 async version of the API

NOTE: boring-tls isn’t supported with async-std

§SMTP over TLS via the rustls crate

Secure SMTP connections using TLS from the rustls crate

rustls: TLS support for the synchronous version of the API
tokio1-rustls: TLS support for the tokio1 async version of the API
async-std1-rustls: TLS support for the async-std1 async version of the API

§rustls crypto backends

The crypto implementation to use with rustls

When the rustls feature is enabled, one of the following crypto backends MUST also be enabled.

aws-lc-rs: use AWS-LC (via aws-lc-rs) as the rustls crypto backend
ring: use ring as the rustls crypto backend

When enabling aws-lc-rs, the fips feature can also be enabled to have rustls use the FIPS certified module of AWS-LC.

aws-lc-rs may require cmake on some platforms to compile. fips always requires cmake and the Go compiler to compile.

§rustls certificate verification backend

The TLS certificate verification backend to use with rustls

When the rustls feature is enabled, one of the following verification backends MUST also be enabled.

rustls-platform-verifier: verify TLS certificate using the OS’s native certificate store (see rustls-platform-verifier)
rustls-native-certs: verify TLS certificates using the platform’s native certificate store (see rustls-native-certs) - when in doubt use rustls-platform-verifier
webpki-roots: verify TLS certificates against Mozilla’s root certificates (see webpki-roots)

The following packages will need to be installed in order for the build stage and the compiled program to run properly.

Verification backend	Distro	Build-time packages	Runtime packages
`rustls-platform-verifier`	Debian	none	`ca-certificates`
`rustls-platform-verifier`	Alpine Linux	none	`ca-certificates`
`rustls-native-certs`	Debian	none	`ca-certificates`
`rustls-native-certs`	Alpine Linux	none	`ca-certificates`
`webpki-roots`	any	none	none

§Sendmail transport

Send emails using the sendmail command

sendmail-transport: Enable the sendmail transport

§File transport

Save emails as an .eml file

file-transport: Enable the file transport (saves emails into an .eml file)
file-transport-envelope: Allow writing the envelope into a JSON file (additionally saves envelopes into a .json file)

§Async execution runtimes

Use tokio or async-std as an async execution runtime for sending emails

The correct runtime version must be chosen in order for lettre to work correctly. For example, when sending emails from a Tokio 1.x context, the Tokio 1.x executor ([Tokio1Executor]) must be used. Using a different version (for example Tokio 0.2.x), or async-std, would result in a runtime panic.

tokio1: Allow to asynchronously send emails using Tokio 1.x
async-std1: Allow to asynchronously send emails using async-std 1.x