From 25153c6b6bf3cbc337b0f8dd36e5bfc405fe810b Mon Sep 17 00:00:00 2001
From: Winni Neessen <wn@neessen.net>
Date: Mon, 14 Mar 2022 10:57:01 +0100
Subject: [PATCH] Updated README.md (added full example)

---
 README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 79 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index bea6054..ff05b81 100644
--- a/README.md
+++ b/README.md
@@ -19,16 +19,90 @@ Some of the features of this library:
 * [X] Only Standard Library dependant
 * [X] Modern, idiomatic Go
 * [X] Sane and secure defaults
-* [X] SSL/TLS support
-* [X] StartTLS support with different policies
+* [X] Explicit SSL/TLS support
+* [X] Implicit StartTLS support with different policies
 * [X] Makes use of contexts for a better control flow and timeout/cancelation handling
 * [X] SMTP Auth support (LOGIN, PLAIN, CRAM-MD)
 * [X] RFC5322 compliant mail address validation
-* [X] Support for common mail header field generation (Message-ID, Date, Bulk-Precedence, etc.)
+* [X] Support for common mail header field generation (Message-ID, Date, Bulk-Precedence, Priority, etc.)
 * [X] Reusing the same SMTP connection to send multiple mails
 * [X] Support for attachments and inline embeds
 * [ ] Support for different encodings (existing but not fully tested)
 
+go-mail works like a programatic email client and provides lots of methods and functionalities you would
+consider standard in a MUA.
+
 ## Examples
-The package is shipped with example code. Check it out on the packages 
-[GoDoc page](https://pkg.go.dev/github.com/wneessen/go-mail#pkg-examples) 
\ No newline at end of file
+The package is shipped with GoDoc example code for difference scenarios. Check them out on its
+[GoDoc page](https://pkg.go.dev/github.com/wneessen/go-mail#pkg-examples) 
+
+For ease of use, here is a full usage example:
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/wneessen/go-mail"
+	"os"
+)
+
+func main() {
+	// Create a new mail message
+	m := mail.NewMsg()
+
+	// To set address header fields like "From", "To", "Cc" or "Bcc" you have different methods
+	// at your hands. Some perform input validation, some ignore invalid addresses. Some perform
+	// the formating for you.
+	// 
+	if err := m.FromFormat("Toni Tester", "sender@example.com"); err != nil {
+		fmt.Printf("failed to set FROM address: %s\n", err)
+		os.Exit(1)
+	}
+	if err := m.To(`"Max Mastermind <rcpt@example.com>"`); err != nil {
+		fmt.Printf("failed to set TO address: %s\n", err)
+		os.Exit(1)
+    }
+	m.CcIgnoreInvalid("cc@example.com")
+	
+	// Set a subject line
+	m.Subject("This is a great email")
+	
+	// And some other common headers
+	m.SetDate()      // Sets a valid "Date" header field with the current time
+	m.SetMessageID() // Generates a valid and unique "Message-ID"
+	m.SetBulk()      // Sets the "Precedence"-Header to "bulk" to indicate a "bulk mail"
+	
+	// Add your mail message to body
+	m.SetBodyString(mail.TypeTextPlain, "This is a great message body text.")
+	
+	// Attach a file from your local FS
+	// We override the attachment name using the WithFileName() Option
+	m.AttachFile("/home/ttester/test.txt", mail.WithFileName("attachment.txt"))
+	
+	// Next let's create a Client
+	// We have lots of With* options at our disposal to stear the Client. It will set sane
+	// options by default, though
+	//
+	// Let's assume we need to perform SMTP AUTH with the sending server, though. Since we
+	// use SMTP PLAIN AUTH, let's also make sure to enforce strong TLS
+	host := "relay.example.com"
+	c, err := mail.NewClient(host, 
+		mail.WithSMTPAuth(mail.SMTPAuthPlain), mail.WithUsername("ttester"),
+		mail.WithPassword("V3rySecUr3!Pw."), mail.WithTLSPolicy(mail.TLSMandatory))
+	if err != nil {
+		fmt.Printf("failed to create new mail client: %s\n", err)
+		os.Exit(1)
+    }
+	
+	// Now that we have our client, we can connect to the server and send our mail message
+	// via the convenient DialAndSend() method. You have the option to Dial() and Send()
+	// seperately as well
+	if err := c.DialAndSend(m); err != nil {
+		fmt.Printf("failed to send mail: %s\n", err)
+		os.Exit(1)
+    }
+	
+	fmt.Println("Mail successfully sent.")
+}
+```
\ No newline at end of file