Updated README.md (added full example)

This commit is contained in:
Winni Neessen 2022-03-14 10:57:01 +01:00
parent 3ca982e312
commit 25153c6b6b
Signed by: wneessen
GPG key ID: 385AC9889632126E

View file

@ -19,16 +19,90 @@ Some of the features of this library:
* [X] Only Standard Library dependant * [X] Only Standard Library dependant
* [X] Modern, idiomatic Go * [X] Modern, idiomatic Go
* [X] Sane and secure defaults * [X] Sane and secure defaults
* [X] SSL/TLS support * [X] Explicit SSL/TLS support
* [X] StartTLS support with different policies * [X] Implicit StartTLS support with different policies
* [X] Makes use of contexts for a better control flow and timeout/cancelation handling * [X] Makes use of contexts for a better control flow and timeout/cancelation handling
* [X] SMTP Auth support (LOGIN, PLAIN, CRAM-MD) * [X] SMTP Auth support (LOGIN, PLAIN, CRAM-MD)
* [X] RFC5322 compliant mail address validation * [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] Reusing the same SMTP connection to send multiple mails
* [X] Support for attachments and inline embeds * [X] Support for attachments and inline embeds
* [ ] Support for different encodings (existing but not fully tested) * [ ] 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 ## Examples
The package is shipped with example code. Check it out on the packages 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) [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.")
}
```