go-mail/README.md

118 lines
7.3 KiB
Markdown
Raw Normal View History

<!--
SPDX-FileCopyrightText: 2022-2023 The go-mail Authors
SPDX-License-Identifier: CC0-1.0
-->
# go-mail - Easy to use, yet comprehensive library for sending mails with Go
2022-03-05 12:10:20 +01:00
2022-03-15 21:48:08 +01:00
[![GoDoc](https://godoc.org/github.com/wneessen/go-mail?status.svg)](https://pkg.go.dev/github.com/wneessen/go-mail)
[![codecov](https://codecov.io/gh/wneessen/go-mail/branch/main/graph/badge.svg?token=37KWJV03MR)](https://codecov.io/gh/wneessen/go-mail)
2022-03-15 14:54:11 +01:00
[![Go Report Card](https://goreportcard.com/badge/github.com/wneessen/go-mail)](https://goreportcard.com/report/github.com/wneessen/go-mail)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)
[![#go-mail on Discord](https://img.shields.io/badge/Discord-%23go%E2%80%93mail-blue.svg)](https://discord.gg/ysQXkaccXk)
[![REUSE status](https://api.reuse.software/badge/github.com/wneessen/go-mail)](https://api.reuse.software/info/github.com/wneessen/go-mail)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8701/badge)](https://www.bestpractices.dev/projects/8701)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/wneessen/go-mail/badge)](https://securityscorecards.dev/viewer/?uri=github.com/wneessen/go-mail)
2022-03-15 14:54:11 +01:00
<a href="https://ko-fi.com/D1D24V9IX"><img src="https://uploads-ssl.webflow.com/5c14e387dab576fe667689cf/5cbed8a4ae2b88347c06c923_BuyMeACoffee_blue.png" height="20" alt="buy ma a coffee"></a>
2022-03-05 12:10:20 +01:00
2022-07-11 10:21:09 +02:00
<p align="center"><img src="./assets/gopher2.svg" width="250" alt="go-mail logo"/></p>
2022-07-08 16:04:04 +02:00
The main idea of this library was to provide a simple interface for sending mails to
2022-03-14 10:57:55 +01:00
my [JS-Mailer](https://github.com/wneessen/js-mailer) project. It quickly evolved into a full-fledged mail library.
2022-03-05 12:10:20 +01:00
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.
2022-03-10 16:19:51 +01:00
In the early days, parts of this library (especially some parts of [msgwriter.go](msgwriter.go)) had been
forked/ported from [go-mail/mail](https://github.com/go-mail/mail) and respectively [go-gomail/gomail](https://github.com/go-gomail/gomail). Today
most of the ported code has been refactored.
2022-03-14 10:33:15 +01:00
The `smtp` package of go-mail has been forked from the original Go stdlib's `net/smtp` package and has then been extended
by the go-mail team to fit the packages needs (more SMTP Auth methods, logging, concurrency-safety, etc.).
2022-03-10 16:19:51 +01:00
## Features
2022-03-14 10:57:55 +01:00
Here are some highlights of go-mail's featureset:
2022-03-14 10:57:55 +01:00
* [X] Very small dependency footprint (mainly Go Stdlib and Go extended packages)
* [X] Modern, idiomatic Go
2022-03-10 16:56:41 +01:00
* [X] Sane and secure defaults
2022-03-14 10:57:01 +01:00
* [X] Explicit SSL/TLS support
* [X] Implicit StartTLS support with different policies
2022-03-10 16:19:51 +01:00
* [X] Makes use of contexts for a better control flow and timeout/cancelation handling
* [X] SMTP Auth support (LOGIN, PLAIN, CRAM-MD, XOAUTH2, SCRAM-SHA-1(-PLUS), SCRAM-SHA-256(-PLUS))
2022-03-10 16:19:51 +01:00
* [X] RFC5322 compliant mail address validation
2022-03-14 10:57:01 +01:00
* [X] Support for common mail header field generation (Message-ID, Date, Bulk-Precedence, Priority, etc.)
* [X] Concurrency-safe reusing the same SMTP connection to send multiple mails
* [X] Support for attachments and inline embeds (from file system, `io.Reader` or `embed.FS`)
* [X] Support for different encodings
* [X] Middleware support for 3rd-party libraries to alter mail messages
* [X] Support sending mails via a local sendmail command
* [X] Support for requestng MDNs (RFC 8098) and DSNs (RFC 1891)
* [X] DKIM signature support via [go-mail-middlware](https://github.com/wneessen/go-mail-middleware)
* [X] Message object satisfies `io.WriteTo` and `io.Reader` interfaces
2022-06-03 10:42:56 +02:00
* [X] Support for Go's `html/template` and `text/template` (as message body, alternative part or attachment/emebed)
* [X] Output to file support which allows storing mail messages as e. g. `.eml` files to disk to open them in a MUA
* [X] Debug logging of SMTP traffic
* [X] Custom error types for delivery errors
* [X] Custom dial-context functions for more control over the connection (proxing, DNS hooking, etc.)
* [X] Output a go-mail message as EML file and parse EML file into a go-mail message
2022-03-10 10:53:38 +01:00
2022-03-14 10:57:55 +01:00
go-mail works like a programatic email client and provides lots of methods and functionalities you would consider
standard in a MUA.
2022-03-14 10:57:01 +01:00
## Documentation
We aim for good GoDoc documenation in our library which gives you a full API reference. We also provide a more in-depth
documentation website at [go-mail.dev](https://go-mail.dev)
2023-02-02 10:18:59 +01:00
## Compatibility
Go is growing fast and providing great features with every new release. While we'd love to adopt the latest Go features
into our code, we realize that not everybody using this package can run the latest Go versions. Therefore we try to
implement alternative solutions for Go versions that do not support these features. Yet, the work needed to maintain
the separate versions is not to be underestimated. For that reason, we might retire that code at some point.
We guarantee that go-mail will always support the last four releases of Go. With two Go releases per year, this gives
the user a timeframe of two years to update to the next or even the latest version of Go.
2022-09-22 16:54:38 +02:00
## Support
We have a support and general discussion channel on Discord. Find us at: [#go-mail](https://discord.gg/dbfQyC4s)
## Middleware
The goal of go-mail is to keep it free from 3rd party dependencies and only focus on things a mail library should
fulfill. Yet, since version v0.2.8 we've added support for middleware on the `Msg` object, allowing 3rd parties to
alter a given mail message to their needs without relying on `go-mail` to support their specific need.
To get our users started with message middleware, we've created a collection of useful middlewares. It can be
found in a seperate repository: [go-mail-middlware](https://github.com/wneessen/go-mail-middleware).
## Merch
Thanks to our wonderful friends at [HelloTux](https://www.hellotux.com) we can offer great go-mail merchandising. All merch articles are embroidery
to provide the best and most long-lasting quality possible.
If you want to support the open source community and represent your favourite Go mail library with some cool drip, check out our merch shop at:
[https://www.hellotux.com/go-mail](https://www.hellotux.com/go-mail).
## Examples
2022-03-14 10:57:55 +01:00
We provide example code in both our GoDocs as well as on our official Website (see [Documentation](#documentation)). For a quick start into go-mail
check out our [Getting started](https://go-mail.dev/getting-started/introduction/) guide.
## Authors/Contributors
go-mail was initially created and developed by [Winni Neessen](https://github.com/wneessen/), but over time a lot of amazing people
contributed ot the project. Big thanks to all of them for improving the go-mail project (be it writing code, testing
code, reviewing code, writing documenation or helping to translate the website):
<a href="https://github.com/wneessen/go-mail/graphs/contributors">
<img src="https://contrib.rocks/image?repo=wneessen/go-mail" />
</a>
A huge thank you also goes to [Maria Letta](https://github.com/MariaLetta) for designing our super cool go-mail logo!
## Sponsors
We sincerely thank our amazing sponsors for their generous support! Your contributions do not go unnoticed and helps
keeping up the project!
* [kolaente](https://github.com/kolaente)