3f5b3cdd98
* feat: add configurable SMTP HELO hostname Allow the SMTP HELO/EHLO hostname to be configured separately from the SMTP server hostname. This is useful when the SMTP server requires clients to identify themselves with a fully qualified hostname different from the server address. * chore: remove vendored dependency changes * Bump go-pkgz/notify to v1.4.0 and document SMTP_HELO_HOST The HELOHost field lands in go-pkgz/notify v1.4.0, so the branch needs the bump to compile; v1.3.0 in master has no such field. The example module is tidied alongside, as any change to backend/go.mod requires. Documents the parameter in the parameters table and, separately, in the email setup page: what it does, that leaving it unset keeps the previous `localhost` greeting, and the case it exists for, a relay refusing the greeting under Postfix `reject_non_fqdn_helo_hostname`. Also records the current limit: verification emails for email authentication go through go-pkgz/auth's own sender, which has no equivalent setting, so the greeting there is unchanged. * Bump go-pkgz/auth to v2.2.0 and apply SMTP_HELO_HOST to verification email The verification email sender had no way to set the greeting, so a relay that refuses the HELO would accept notifications and still reject sign-in emails. EmailParams gains HELOHost in go-pkgz/auth v2.2.0, so the same SMTP_HELO_HOST now drives both paths. The example module is tidied alongside, as any change to backend/go.mod requires. --------- Co-authored-by: oli <someone@somewhere.tld> Co-authored-by: Dmitry Verkhoturov <paskal.07@gmail.com>
email sending library
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:
client := email.NewSender("localhost", email.ContentType("text/html"), email.Auth("user", "pass"))
err := client.Send("<html>some content, foo bar</html>",
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)InsecureSkipVerify: skip certificate verification (default: false)HELOHost: SMTP HELO/EHLO hostname (default: empty, greets aslocalhost). Some servers rejectlocalhost, e.g. Postfix withreject_non_fqdn_helo_hostname. Not applied to a custom client set withSMTP.Auth(user, password): Username and password for SMTP authentication (default: empty, no authentication)LoginAuth: Use LOGIN mechanism instead of PLAIN mechanism for SMTP authentication, e.g. this is relevant for Office 365 and Outlook.comContentType: 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 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)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 for Send function.
SendContext takes the same parameters with a context added and is the way to bound the time spent on sending.
The TimeOut option covers the connection setup only, while the context covers the whole SMTP transaction,
so a server accepting the connection and stalling afterwards terminates the send instead of blocking the caller:
ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
defer cancel()
err := client.SendContext(ctx, "some content", email.Params{From: "me@example.com", To: []string{"to@example.com"}})
A custom smtp client set with the SMTP option owns its connection, and such a transaction can't be
terminated in the middle; the context is checked before it starts in that case.
technical details
- Content-Transfer-Encoding set to
quoted-printable - Custom SMTP client (
smtp.Clientfrom stdlib) can be set by user withSMTPoption. In this case it will be used instead of making a new smtp client internally. - Logger can be set with
Logoption. It should implementemail.Loggerinterface with a singleLogf(format string, args ...interface{})method. By default, "no logging" internal logger is used. This interface is compatible with thego-pkgz/lgrlogger. - The library has no external dependencies, except for testing. It uses the stdlib
net/smtppackage. - SSL/TLS supported with
TLSoption (usually on port 465) as well as withSTARTTLS(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.