Home

go-mail - Easy to use, yet comprehensive library for sending mails with Go

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

Table of contents

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

What is go-mail?

go-mail is an easy to use Go library for formating and sending mails. go-mail follows idiomatic Go style and best practice. It has a small dependency footprint by mainly relying on the Go Standard Library and the Go extended packages. It combines a lot of functionality from the standard library to give easy and convenient access to mail and SMTP related tasks. It works like a programatic email client and provides lots of methods and functionalities you would consider standard in a MUA.

History of go-mail

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.

What is go-mail for?

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).

What features does go-mail's have?

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
  • 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 or embed.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 requestng MDNs (RFC 8098) and DSNs (RFC 1891)
• DKIM signature support via go-mail-middlware
• 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/emebed)
• 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