From 2d21dde5a15b4ad605b3181de8fd8c76aedeb04c Mon Sep 17 00:00:00 2001
From: Paolo Barbolini <paolo@paolo565.org>
Date: Fri, 17 Jun 2022 08:35:07 +0200
Subject: [PATCH] Add autoconfigure.rs example (#787)

---
 Cargo.toml                |  5 +++
 README.md                 |  8 ++++
 examples/autoconfigure.rs | 93 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 106 insertions(+)
 create mode 100644 examples/autoconfigure.rs

diff --git a/Cargo.toml b/Cargo.toml
index ca9300e..5f4f7e3 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -74,6 +74,7 @@ email_address = { version = "0.2.1", default-features = false }
 [dev-dependencies]
 pretty_assertions = "1"
 criterion = "0.3"
+tracing = { version = "0.1.16", default-features = false, features = ["std"] }
 tracing-subscriber = "0.3"
 glob = "0.3"
 walkdir = "2"
@@ -115,6 +116,10 @@ dkim = ["base64", "sha2", "rsa", "ed25519-dalek", "regex", "once_cell"]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs", "--cfg", "lettre_ignore_tls_mismatch"]
 
+[[example]]
+name = "autoconfigure"
+required-features = ["smtp-transport", "native-tls"]
+
 [[example]]
 name = "basic_html"
 required-features = ["file-transport", "builder"]
diff --git a/README.md b/README.md
index 4d2ce83..42114fa 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,14 @@ match mailer.send(&email) {
 }
 ```
 
+## Not sure of which connect options to use?
+
+Clone the lettre git repository and run the following command (replacing `SMTP_HOST` with your SMTP server's hostname)
+
+```shell
+cargo run --example autoconfigure SMTP_HOST
+```
+
 ## Testing
 
 The `lettre` tests require an open mail server listening locally on port 2525 and the `sendmail` command. If you have python installed 
diff --git a/examples/autoconfigure.rs b/examples/autoconfigure.rs
new file mode 100644
index 0000000..93512c6
--- /dev/null
+++ b/examples/autoconfigure.rs
@@ -0,0 +1,93 @@
+use std::{env, process, time::Duration};
+
+use lettre::SmtpTransport;
+
+fn main() {
+    tracing_subscriber::fmt::init();
+
+    let smtp_host = match env::args().nth(1) {
+        Some(smtp_host) => smtp_host,
+        None => {
+            println!("Please provide the SMTP host as the first argument to this command");
+            process::exit(1);
+        }
+    };
+
+    // TLS wrapped connection
+    {
+        tracing::info!(
+            "Trying to establish a TLS wrapped connection to {}",
+            smtp_host
+        );
+
+        let transport = SmtpTransport::relay(&smtp_host)
+            .expect("build SmtpTransport::relay")
+            .timeout(Some(Duration::from_secs(10)))
+            .build();
+        match transport.test_connection() {
+            Ok(true) => {
+                tracing::info!("Successfully connected to {} via a TLS wrapped connection (SmtpTransport::relay). This is the fastest option available for connecting to an SMTP server", smtp_host);
+            }
+            Ok(false) => {
+                tracing::error!("Couldn't connect to {} via a TLS wrapped connection. No more information is available", smtp_host);
+            }
+            Err(err) => {
+                tracing::error!(err = %err, "Couldn't connect to {} via a TLS wrapped connection", smtp_host);
+            }
+        }
+    }
+
+    println!();
+
+    // Plaintext connection which MUST then successfully upgrade to TLS via STARTTLS
+    {
+        tracing::info!("Trying to establish a plaintext connection to {} and then updating it via the SMTP STARTTLS extension", smtp_host);
+
+        let transport = SmtpTransport::starttls_relay(&smtp_host)
+            .expect("build SmtpTransport::starttls_relay")
+            .timeout(Some(Duration::from_secs(10)))
+            .build();
+        match transport.test_connection() {
+            Ok(true) => {
+                tracing::info!("Successfully connected to {} via a plaintext connection which then got upgraded to TLS via the SMTP STARTTLS extension (SmtpTransport::starttls_relay). This is the second best option after the previous TLS wrapped option", smtp_host);
+            }
+            Ok(false) => {
+                tracing::error!(
+                    "Couldn't connect to {} via STARTTLS. No more information is available",
+                    smtp_host
+                );
+            }
+            Err(err) => {
+                tracing::error!(err = %err, "Couldn't connect to {} via STARTTLS", smtp_host);
+            }
+        }
+    }
+
+    println!();
+
+    // Plaintext connection (very insecure)
+    {
+        tracing::info!(
+            "Trying to establish a plaintext connection to {}",
+            smtp_host
+        );
+
+        let transport = SmtpTransport::builder_dangerous(&smtp_host)
+            .timeout(Some(Duration::from_secs(10)))
+            .build();
+        match transport.test_connection() {
+            Ok(true) => {
+                tracing::info!("Successfully connected to {} via a plaintext connection. This option is very insecure and shouldn't be used on the public internet (SmtpTransport::builder_dangerous)", smtp_host);
+            }
+            Ok(false) => {
+                tracing::error!(
+                    "Couldn't connect to {} via a plaintext connection. No more information is available",
+                    smtp_host
+                );
+            }
+            Err(err) => {
+                tracing::error!(err = %err, "Couldn't connect to {} via a plaintext connection", smtp_host);
+            }
+        }
+    }
+}