From fbbd0151095fee4e22f738a0c6ce291a59330e09 Mon Sep 17 00:00:00 2001 From: Paolo Barbolini Date: Sun, 2 Aug 2020 22:27:35 +0200 Subject: [PATCH] Update docs and examples for 0.10 --- Cargo.toml | 2 +- README.md | 58 +++++++++++++++++++++++------------------- examples/smtp.rs | 13 ++++------ examples/smtp_gmail.rs | 19 +++++--------- src/lib.rs | 5 ++-- 5 files changed, 47 insertions(+), 50 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index d5cd29f..56ad6bf 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "lettre" -version = "0.10.0-alpha.0" # remember to update html_root_url +version = "0.10.0-alpha.0" # remember to update html_root_url and README.md description = "Email client" readme = "README.md" homepage = "https://lettre.at" diff --git a/README.md b/README.md index 562aafd..ebbd821 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,14 @@ --- +**NOTE**: this readme refers to the 0.10 version of lettre, which is +still being worked on. The master branch and the alpha releases will see +API breaking changes and some features may be missing or incomplete until +the stable 0.10.0 release is out. +Use the [`v0.9.x`](https://github.com/lettre/lettre/tree/v0.9.x) branch for stable releases. + +--- + ## Features Lettre provides the following features: @@ -37,58 +45,56 @@ Lettre provides the following features: * Unicode support (for email content and addresses) * Secure delivery with SMTP using encryption and authentication * Easy email builders +* Async support (incomplete) Lettre does not provide (for now): -* Async support * Email parsing ## Example -This library requires Rust 1.20 or newer. +This library requires Rust 1.40 or newer. To use this library, add the following to your `Cargo.toml`: ```toml [dependencies] -lettre = "0.9" -lettre_email = "0.9" +lettre = "0.10.0-alpha.1" ``` ```rust,no_run -use lettre::{EmailTransport, SmtpTransport}; -use lettre_email::EmailBuilder; -use std::path::Path; +use lettre::transport::smtp::authentication::Credentials; +use lettre::{Message, SmtpTransport, Transport}; -let email = EmailBuilder::new() - // Addresses can be specified by the tuple (email, alias) - .to(("user@example.org", "Firstname Lastname")) - // ... or by an address only - .from("user@example.com") - .subject("Hi, Hello world") - .text("Hello world.") - .build() +let email = Message::builder() + .from("NoBody ".parse().unwrap()) + .reply_to("Yuin ".parse().unwrap()) + .to("Hei ".parse().unwrap()) + .subject("Happy new year") + .body("Be happy!") .unwrap(); -// Open a local connection on port 25 -let mut mailer = SmtpTransport::builder_unencrypted_localhost().unwrap() - .build(); +let creds = Credentials::new("smtp_username".to_string(), "smtp_password".to_string()); + +// Open a remote connection to gmail +let mailer = SmtpTransport::relay("smtp.gmail.com") + .unwrap() + .credentials(creds) + .build(); + // Send the email -let result = mailer.send(&email); - -if result.is_ok() { - println!("Email sent"); -} else { - println!("Could not send email: {:?}", result); +match mailer.send(&email) { + Ok(_) => println!("Email sent successfully!"), + Err(e) => panic!("Could not send email: {:?}", e), } - -assert!(result.is_ok()); ``` ## Testing The `lettre` tests require an open mail server listening locally on port 2525 and the `sendmail` command. +Alternatively only unit tests can be run by doing `cargo test --lib`. + ## Code of conduct Anyone who interacts with Lettre in any space, including but not limited to diff --git a/examples/smtp.rs b/examples/smtp.rs index 9448ffd..f2b8b31 100644 --- a/examples/smtp.rs +++ b/examples/smtp.rs @@ -2,6 +2,7 @@ use lettre::{Message, SmtpTransport, Transport}; fn main() { env_logger::init(); + let email = Message::builder() .from("NoBody ".parse().unwrap()) .reply_to("Yuin ".parse().unwrap()) @@ -12,14 +13,10 @@ fn main() { // Open a local connection on port 25 let mailer = SmtpTransport::unencrypted_localhost(); + // Send the email - let result = mailer.send(&email); - - if result.is_ok() { - println!("Email sent"); - } else { - println!("Could not send email: {:?}", result); + match mailer.send(&email) { + Ok(_) => println!("Email sent successfully!"), + Err(e) => panic!("Could not send email: {:?}", e), } - - assert!(result.is_ok()); } diff --git a/examples/smtp_gmail.rs b/examples/smtp_gmail.rs index 95b294c..f5dee63 100644 --- a/examples/smtp_gmail.rs +++ b/examples/smtp_gmail.rs @@ -1,4 +1,5 @@ -use lettre::{transport::smtp::authentication::Credentials, Message, SmtpTransport, Transport}; +use lettre::transport::smtp::authentication::Credentials; +use lettre::{Message, SmtpTransport, Transport}; fn main() { let email = Message::builder() @@ -9,10 +10,7 @@ fn main() { .body("Be happy!") .unwrap(); - let creds = Credentials::new( - "example_username".to_string(), - "example_password".to_string(), - ); + let creds = Credentials::new("smtp_username".to_string(), "smtp_password".to_string()); // Open a remote connection to gmail let mailer = SmtpTransport::relay("smtp.gmail.com") @@ -21,13 +19,8 @@ fn main() { .build(); // Send the email - let result = mailer.send(&email); - - if result.is_ok() { - println!("Email sent"); - } else { - println!("Could not send email: {:?}", result); + match mailer.send(&email) { + Ok(_) => println!("Email sent successfully!"), + Err(e) => panic!("Could not send email: {:?}", e), } - - assert!(result.is_ok()); } diff --git a/src/lib.rs b/src/lib.rs index 2f0ef0b..35c947b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -137,7 +137,7 @@ impl TryFrom<&Headers> for Envelope { } } -/// Transport method for emails +/// Blocking Transport method for emails pub trait Transport { /// Result types for the transport type Ok: fmt::Debug; @@ -153,7 +153,7 @@ pub trait Transport { fn send_raw(&self, envelope: &Envelope, email: &[u8]) -> Result; } -/// Async Transport method for emails +/// async-std 1.x based Transport method for emails #[cfg(feature = "async-std1")] #[async_trait] pub trait AsyncStd1Transport { @@ -173,6 +173,7 @@ pub trait AsyncStd1Transport { async fn send_raw(&self, envelope: &Envelope, email: &[u8]) -> Result; } +/// tokio 0.2.x based Transport method for emails #[cfg(feature = "tokio02")] #[async_trait] pub trait Tokio02Transport {