From 47dfdf7ee8e39bee00cee3ca25a8369dbcd01407 Mon Sep 17 00:00:00 2001 From: Alexis Mousset Date: Wed, 9 Sep 2020 09:29:40 +0200 Subject: [PATCH] Add back removed examples --- src/lib.rs | 15 ++--- src/message/header/mailbox.rs | 12 ++-- src/message/mailbox/types.rs | 6 ++ src/transport/smtp/client/mod.rs | 21 +++++++ src/transport/smtp/mod.rs | 101 +++++++++++++++++++++++++++++++ 5 files changed, 138 insertions(+), 17 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 7f5cfc2..84f0652 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -207,10 +207,8 @@ mod test { #[test] fn envelope_from_headers() { - let mut from = Mailboxes::new(); - from.push("kayo@example.com".parse().unwrap()); - let mut to = Mailboxes::new(); - to.push("amousset@example.com".parse().unwrap()); + let from = Mailboxes::new().with("kayo@example.com".parse().unwrap()); + let to = Mailboxes::new().with("amousset@example.com".parse().unwrap()); let mut headers = Headers::new(); headers.set(header::From(from)); @@ -228,11 +226,9 @@ mod test { #[test] fn envelope_from_headers_sender() { - let mut from = Mailboxes::new(); - from.push("kayo@example.com".parse().unwrap()); + let from = Mailboxes::new().with("kayo@example.com".parse().unwrap()); let sender = Mailbox::new(None, "kayo2@example.com".parse().unwrap()); - let mut to = Mailboxes::new(); - to.push("amousset@example.com".parse().unwrap()); + let to = Mailboxes::new().with("amousset@example.com".parse().unwrap()); let mut headers = Headers::new(); headers.set(header::From(from)); @@ -251,8 +247,7 @@ mod test { #[test] fn envelope_from_headers_no_to() { - let mut from = Mailboxes::new(); - from.push("kayo@example.com".parse().unwrap()); + let from = Mailboxes::new().with("kayo@example.com".parse().unwrap()); let sender = Mailbox::new(None, "kayo2@example.com".parse().unwrap()); let mut headers = Headers::new(); diff --git a/src/message/header/mailbox.rs b/src/message/header/mailbox.rs index b946e5d..913c755 100644 --- a/src/message/header/mailbox.rs +++ b/src/message/header/mailbox.rs @@ -169,8 +169,7 @@ mod test { #[test] fn format_single_without_name() { - let mut from = Mailboxes::new(); - from.push("kayo@example.com".parse().unwrap()); + let from = Mailboxes::new().with("kayo@example.com".parse().unwrap()); let mut headers = Headers::new(); headers.set(From(from)); @@ -180,8 +179,7 @@ mod test { #[test] fn format_single_with_name() { - let mut from = Mailboxes::new(); - from.push("K. ".parse().unwrap()); + let from = Mailboxes::new().with("K. ".parse().unwrap()); let mut headers = Headers::new(); headers.set(From(from)); @@ -191,9 +189,9 @@ mod test { #[test] fn format_multi_without_name() { - let mut from = Mailboxes::new(); - from.push("kayo@example.com".parse().unwrap()); - from.push("pony@domain.tld".parse().unwrap()); + let from = Mailboxes::new() + .with("kayo@example.com".parse().unwrap()) + .with("pony@domain.tld".parse().unwrap()); let mut headers = Headers::new(); headers.set(From(from)); diff --git a/src/message/mailbox/types.rs b/src/message/mailbox/types.rs index bdcccc0..305d20c 100644 --- a/src/message/mailbox/types.rs +++ b/src/message/mailbox/types.rs @@ -113,6 +113,12 @@ impl Mailboxes { Mailboxes(Vec::new()) } + /// Add mailbox to a list + pub fn with(mut self, mbox: Mailbox) -> Self { + self.0.push(mbox); + self + } + /// Add mailbox to a list pub fn push(&mut self, mbox: Mailbox) { self.0.push(mbox); diff --git a/src/transport/smtp/client/mod.rs b/src/transport/smtp/client/mod.rs index cba13cf..50f71ef 100644 --- a/src/transport/smtp/client/mod.rs +++ b/src/transport/smtp/client/mod.rs @@ -1,4 +1,25 @@ //! SMTP client +//! +//! `SmtpConnection` allows manually sending SMTP commands. +//! +//! ```rust,no_run +//! # #[cfg(feature = "smtp-transport")] +//! # { +//! use lettre::transport::smtp::{SMTP_PORT, extension::ClientId, commands::*, client::SmtpConnection}; +//! +//! let hello = ClientId::Domain("my_hostname".to_string()); +//! let mut client = SmtpConnection::connect(&("localhost", SMTP_PORT), None, &hello, None).unwrap(); +//! client.command( +//! Mail::new(Some("user@example.com".parse().unwrap()), vec![]) +//! ).unwrap(); +//! client.command( +//! Rcpt::new("user@example.org".parse().unwrap(), vec![]) +//! ).unwrap(); +//! client.command(Data).unwrap(); +//! client.message("Test email".as_bytes()).unwrap(); +//! client.command(Quit).unwrap(); +//! # } +//! ``` #[cfg(feature = "serde")] use std::fmt::Debug; diff --git a/src/transport/smtp/mod.rs b/src/transport/smtp/mod.rs index 03fe6ee..00c1505 100644 --- a/src/transport/smtp/mod.rs +++ b/src/transport/smtp/mod.rs @@ -53,6 +53,107 @@ //! # } //! ``` +//! #### Complete example +//! +//! ```todo +//! # #[cfg(feature = "smtp-transport")] +//! # { +//! use lettre::transport::smtp::authentication::{Credentials, Mechanism}; +//! use lettre::{Email, Envelope, Transport, SmtpClient}; +//! use lettre::transport::smtp::extension::ClientId; +//! +//! let email_1 = Email::new( +//! Envelope::new( +//! Some(EmailAddress::new("user@localhost".to_string()).unwrap()), +//! vec![EmailAddress::new("root@localhost".to_string()).unwrap()], +//! ).unwrap(), +//! "id1".to_string(), +//! "Hello world".to_string().into_bytes(), +//! ); +//! +//! let email_2 = Email::new( +//! Envelope::new( +//! Some(EmailAddress::new("user@localhost".to_string()).unwrap()), +//! vec![EmailAddress::new("root@localhost".to_string()).unwrap()], +//! ).unwrap(), +//! "id2".to_string(), +//! "Hello world a second time".to_string().into_bytes(), +//! ); +//! +//! // Connect to a remote server on a custom port +//! let mut mailer = SmtpClient::new_simple("server.tld").unwrap() +//! // Set the name sent during EHLO/HELO, default is `localhost` +//! .hello_name(ClientId::Domain("my.hostname.tld".to_string())) +//! // Add credentials for authentication +//! .credentials(Credentials::new("username".to_string(), "password".to_string())) +//! // Enable SMTPUTF8 if the server supports it +//! .smtp_utf8(true) +//! // Configure expected authentication mechanism +//! .authentication_mechanism(Mechanism::Plain) +//! // Enable connection reuse +//! .connection_reuse(ConnectionReuseParameters::ReuseUnlimited).transport(); +//! +//! let result_1 = mailer.send(&email_1); +//! assert!(result_1.is_ok()); +//! +//! // The second email will use the same connection +//! let result_2 = mailer.send(&email_2); +//! assert!(result_2.is_ok()); +//! +//! // Explicitly close the SMTP transaction as we enabled connection reuse +//! mailer.close(); +//! # } +//! ``` +//! +//! You can specify custom TLS settings: +//! +//! ```todo +//! # #[cfg(feature = "native-tls")] +//! # { +//! use lettre::{ +//! ClientSecurity, ClientTlsParameters, EmailAddress, Envelope, +//! Email, SmtpClient, Transport, +//! }; +//! use lettre::transport::smtp::authentication::{Credentials, Mechanism}; +//! use lettre::transport::smtp::ConnectionReuseParameters; +//! use native_tls::{Protocol, TlsConnector}; +//! +//! let email = Email::new( +//! Envelope::new( +//! Some(EmailAddress::new("user@localhost".to_string()).unwrap()), +//! vec![EmailAddress::new("root@localhost".to_string()).unwrap()], +//! ).unwrap(), +//! "message_id".to_string(), +//! "Hello world".to_string().into_bytes(), +//! ); +//! +//! let mut tls_builder = TlsConnector::builder(); +//! tls_builder.min_protocol_version(Some(Protocol::Tlsv10)); +//! let tls_parameters = +//! ClientTlsParameters::new( +//! "smtp.example.com".to_string(), +//! tls_builder.build().unwrap() +//! ); +//! +//! let mut mailer = SmtpClient::new( +//! ("smtp.example.com", 465), ClientSecurity::Wrapper(tls_parameters) +//! ).unwrap() +//! .authentication_mechanism(Mechanism::Login) +//! .credentials(Credentials::new( +//! "example_username".to_string(), "example_password".to_string() +//! )) +//! .connection_reuse(ConnectionReuseParameters::ReuseUnlimited) +//! .transport(); +//! +//! let result = mailer.send(&email); +//! +//! assert!(result.is_ok()); +//! +//! mailer.close(); +//! # } +//! ``` +//! + use std::time::Duration; #[cfg(feature = "tokio02")]