Module lettre::transport

source ·
Expand description

§Transports for sending emails

This module contains Transports for sending emails. A Transport implements a high-level API for sending emails. It automatically manages the underlying resources and doesn’t require any specific knowledge of email protocols in order to be used.

§Getting started

Sending emails from your programs requires using an email relay, as client libraries are not designed to handle email delivery by themselves. Depending on your infrastructure, your relay could be:

  • a service from your Cloud or hosting provider
  • an email server (MTA for Mail Transfer Agent, like Postfix or Exchange), running either locally on your servers or accessible over the network
  • a dedicated external service, like Mailchimp, Mailgun, etc.

In most cases, the best option is to:

  • Use the SMTP transport, with the relay builder (or one of its async counterparts) with your server’s hostname. They provide modern and secure defaults.
  • Use the credentials method of the builder to pass your credentials.

These should be enough to safely cover most use cases.

§Available transports

The following transports are available:

ModuleProtocolSync APIAsync APIDescription
smtpSMTPSmtpTransportAsyncSmtpTransportUses the SMTP protocol to send emails to a relay server
sendmailSendmailSendmailTransportAsyncSendmailTransportUses the sendmail command to send emails
fileFileFileTransportAsyncFileTransportSaves the email as an .eml file
stubDebugStubTransportAsyncStubTransportDrops the email - Useful for debugging

§Building an email

Emails can either be built though Message, which is a typed API for constructing emails (find out more about it by going over the message module), or via external means.

Messages can be sent via Transport::send or AsyncTransport::send, while messages built without lettre’s message APIs can be sent via Transport::send_raw or AsyncTransport::send_raw.

§Brief example

This example shows how to build an email and send it via an SMTP relay server. It is in no way a complete example, but it shows how to get started with lettre. More examples can be found by looking at the specific modules, linked in the Module column of the table above.

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

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

let creds = Credentials::new("smtp_username".to_owned(), "smtp_password".to_owned());

// Open a remote connection to the SMTP relay server
let mailer = SmtpTransport::relay("smtp.gmail.com")?
    .credentials(creds)
    .build();

// Send the email
match mailer.send(&email) {
    Ok(_) => println!("Email sent successfully!"),
    Err(e) => panic!("Could not send email: {e:?}"),
}

Modules§

  • filefile-transport
    The file transport writes the emails to the given directory. The name of the file will be message_id.eml. It can be useful for testing purposes, or if you want to keep track of sent messages.
  • sendmailsendmail-transport
    The sendmail transport sends the email using the local sendmail command.
  • smtpsmtp-transport
    The SMTP transport sends emails using the SMTP protocol.
  • stub
    The stub transport logs message envelopes as well as contents. It can be useful for testing purposes.

Traits§