mirror of
https://github.com/wneessen/go-mail.git
synced 2024-11-24 22:50:49 +01:00
Winni Neessen
a820ba3cee
Fixed a typo in the README where `io.WriteTo` was incorrectly spelled instead of `io.WriterTo`. This ensures the documentation correctly reflects the interfaces implemented by the Message object.
118 lines
7.4 KiB
Markdown
118 lines
7.4 KiB
Markdown
<!--
|
|
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
|
|
|
|
[](https://pkg.go.dev/github.com/wneessen/go-mail)
|
|
[](https://codecov.io/gh/wneessen/go-mail)
|
|
[](https://goreportcard.com/report/github.com/wneessen/go-mail)
|
|
[](https://github.com/avelino/awesome-go)
|
|
[](https://discord.gg/ysQXkaccXk)
|
|
[](https://api.reuse.software/info/github.com/wneessen/go-mail)
|
|
[](https://www.bestpractices.dev/projects/8701)
|
|
[](https://securityscorecards.dev/viewer/?uri=github.com/wneessen/go-mail)
|
|
<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>
|
|
|
|
<p align="center"><img src="./assets/gopher2.svg" width="250" alt="go-mail logo"/></p>
|
|
|
|
The main idea of this library was to provide a simple interface for sending mails to
|
|
my [JS-Mailer](https://github.com/wneessen/js-mailer) project. It quickly evolved into a full-fledged mail library.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.).
|
|
|
|
## Features
|
|
|
|
Here are some highlights of go-mail's featureset:
|
|
|
|
* [X] Very small dependency footprint (mainly Go Stdlib and Go extended packages)
|
|
* [X] Modern, idiomatic Go
|
|
* [X] Sane and secure defaults
|
|
* [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, XOAUTH2, SCRAM-SHA-1(-PLUS), SCRAM-SHA-256(-PLUS))
|
|
* [X] RFC5322 compliant mail address validation
|
|
* [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.WriterTo` and `io.Reader` interfaces
|
|
* [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
|
|
|
|
go-mail works like a programatic email client and provides lots of methods and functionalities you would consider
|
|
standard in a MUA.
|
|
|
|
## 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)
|
|
|
|
## 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.
|
|
|
|
## Support
|
|
We have a support and general discussion channel on Discord. Find us at: [#go-mail](https://discord.gg/dbfQyC4s) alternatively find us
|
|
on the [Gophers Slack](https://gophers.slack.com) in #go-mail
|
|
|
|
## 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
|
|
|
|
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)
|