Welcome to the go-mail wiki. On the following pages we provide some insights and documentation to go-mail.

• What is go-mail?
  • History of go-mail
• What is go-mail for?
• What features does go-mail's have

go-mail is a modern, feature-rich library for composing and sending mail with Go. It offers a simple, idiomatic interface for everyday use while providing the depth and flexibility needed for advanced email workflows.

Designed around Go best practices, go-mail keeps a small dependency footprint by building primarily on the Go Standard Library and the official Go extended packages. It brings together mail composition, encoding, signing and SMTP delivery into a single, convenient package - giving you the capabilities of a full mail user agent (MUA), programmatically.

Its feature set is extensive, ranging from a wide selection of SMTP authentication mechanisms and TLS options to DKIM and S/MIME signing, attachments and inline embeds, templating, middleware, EML import/export and more (see the full list below).

The smtp package of go-mail was originally forked from Go's standard library net/smtp package and has since been extended by the go-mail team to fit the library's needs - additional SMTP authentication methods, logging, concurrency safety and more.

The main idea of this package was to provide a simple interface for sending mails to mail service I built, which allows to send mails with JavaScript on static websites (JS-Mailer). I initially used go-mail/mail but I quickly realized that some crucial features were missing and I really disliked some design decisions. So one weekend in March of 2022, I sat down and worked on the first version of go-mail and commited into this repository. Meanwhile go-mail has grown a lot and is probably the Go mail package with the most features.

go-mail acts as mail client for your Go programs. The Go standard library provides net/smtp which allows very low-level and basic SMTP operations. In other words, it takes the communication with the SMTP server of your hands but it leaves everything else to the user. This is where go-mail comes in. We use net/smtp ourselves (even though we forked and extended it a lot) and add a MUA-like layer on top. We handle stuff like encodings, headers, attachments, etc. for you.

So, if you write a application or library in Go and you are required to create and/or send mails, go-mail is for you! We've seperated the SMTP client from the mail message, which allows you to generate mails even if you are not planning to send them out (i. e. you need RFC compliant EML files).

Over time, go-mail has grown an extensive featureset. Here are some highlights of what go-mail can offer you:

• Very small dependency footprint (mainly Go Stdlib and Go extended packages)
• Modern, idiomatic Go
• Sane and secure defaults
• Implicit SSL/TLS support
• Explicit STARTTLS support with different policies
• Makes use of contexts for a better control flow and timeout/cancelation handling
• SMTP Auth support
  • CRAM-MD5
  • LOGIN
  • PLAIN
  • NTLM
  • SCRAM-SHA-1/SCRAM-SHA-1-PLUS
  • SCRAM-SHA-256/SCRAM-SHA-256-PLUS
  • XOAUTH2
• RFC5322 compliant mail address validation
• Support for common mail header field generation (Message-ID, Date, Bulk-Precedence, Priority, etc.)
• Concurrency-safe reusing the same SMTP connection to send multiple mails
• Support for attachments and inline embeds (from file system, io.Reader, embed.FS or fs.FS)
• Support for different encodings
• Middleware support for 3rd-party libraries to alter mail messages
• Support sending mails via a local sendmail command
• Support for requesting MDNs (RFC 8098) and DSNs (RFC 1891)
• DomainKeys Identified Mail (DKIM) signature support
• Message object satisfies io.WriterTo and io.Reader interfaces
• Support for Go's html/template and text/template (as message body, alternative part or attachment/embed)
• Output to file support which allows storing mail messages as e. g. .eml files to disk to open them in a MUA
• Debug logging of SMTP traffic
• Custom error types for delivery errors
• Custom dial-context functions for more control over the connection (proxing, DNS hooking, etc.)
• Output a go-mail message as EML file and parse EML file into a go-mail message
• S/MIME message signing support (RSA and ECDSA)
• UNIX domain socket support
• Pluggable SMTP error registry for advanced handling of non-RFC-conforming servers