# email sending library [![Build Status](https://github.com/go-pkgz/email/workflows/build/badge.svg)](https://github.com/go-pkgz/email/actions) [![Coverage Status](https://coveralls.io/repos/github/go-pkgz/email/badge.svg?branch=master)](https://coveralls.io/github/go-pkgz/email?branch=master) [![Go Reference](https://pkg.go.dev/badge/github.com/go-pkgz/email.svg)](https://pkg.go.dev/github.com/go-pkgz/email) The library is a wrapper around the stdlib `net/smtp` simplifying email sending. It supports authentication, SSL/TLS, user-specified SMTP servers, content-type, charset, multiple recipients and more. Usage example: ```go client := email.NewSender("localhost", email.ContentType("text/html"), email.Auth("user", "pass")) err := client.Send("some content, foo bar", email.Params{From: "me@example.com", To: []string{"to@example.com"}, Subject: "Hello world!", Attachments: []string{"/path/to/file1.txt", "/path/to/file2.txt"}, InlineImages: []string{"/path/to/image1.png", "/path/to/image2.png"}, }) ``` ## options `NewSender` accepts a number of options to configure the client: - `Port`: SMTP port (default: 25) - `TLS`: Use TLS SMTP (default: false) - `STARTTLS`: Use STARTTLS (default: false) - `Auth(user, password)`: Username and password for SMTP authentication (default: empty, no authentication) - `LoginAuth`: Use [LOGIN mechanism](https://www.ietf.org/archive/id/draft-murchison-sasl-login-00.txt) instead of PLAIN mechanism for SMTP authentication, e.g. this is relevant for Office 365 and Outlook.com - `ContentType`: Content type for the email (default: "text/plain") - `Charset`: Charset for the email (default: "utf-8") - `TimeOut`: Timeout for the SMTP connection (default: 30 seconds) - `Log`: Logger to use (default: no logging) - `SMTP`: Set custom smtp client (default: none) See [go docs](https://pkg.go.dev/github.com/go-pkgz/email#Option) for `Option` functions. _Options should be passed to `NewSender` after the mandatory first (host) parameter._ ## sending email To send email user need to create a sender first and then use `Send` method. The method accepts two parameters: - email content (string) - parameters (`email.Params`) ```go type Params struct { From string // From email field To []string // From email field Subject string // Email subject UnsubscribeLink string // POST, https://support.google.com/mail/answer/81126 -> "Use one-click unsubscribe" InReplyTo string // Identifier for email group (category), used for email grouping Attachments []string // Attachments path InlineImages []string // Embedding directly to email body. Autogenerated Content-Id (cid) equals to file name } ``` See [go docs](https://pkg.go.dev/github.com/go-pkgz/email#Sender.Send) for `Send` function. ## technical details - Content-Transfer-Encoding set to `quoted-printable` - Custom SMTP client (`smtp.Client` from stdlib) can be set by user with `SMTP` option. In this case it will be used instead of making a new smtp client internally. - Logger can be set with `Log` option. It should implement `email.Logger` interface with a single `Logf(format string, args ...interface{})` method. By default, "no logging" internal logger is used. This interface is compatible with the `go-pkgz/lgr` logger. - The library has no external dependencies, except for testing. It uses the stdlib `net/smtp` package. - SSL/TLS supported with `TLS` option (usually on port 465) as well as with `STARTTLS` (usually on port 587). ## limitations This library is not intended to be used for sending a lot of massive emails with low latency requirements. The intended use case is sending simple messages, like alerts, notification and so on. For example, sending alerts from a monitoring system, or for authentication-related emails, i.e. "password reset email", "verification email", etc.