Documentation
¶
Overview ¶
Package mail sends e-mail for modules: confirmations, notifications and newsletters. A site picks the Sender in webthings.Config.Mail; SMTP is built in, other providers implement Sender. Without one, messages are logged instead of sent, which suits development.
Index ¶
Constants ¶
const DefaultSMTPTimeout = 30 * time.Second
DefaultSMTPTimeout bounds one SMTP.Send when SMTP.Timeout is zero.
const Rule = "mail"
Rule is the name of the go-form validation of addresses mail can be sent to, validate:"mail" on a field, which the site's visitor forms and the admin's forms register (see FormRule):
Email string `form:"input,email" name:"email" required:"true" validate:"mail"`
Variables ¶
This section is empty.
Functions ¶
func FormRule ¶
func FormRule(value any, field reflect.StructField, _ form.Localizer) form.FieldErrors
FormRule is the go-form validation Rule (a form.LocalizedValidationFunc): an address that is not Valid gets go-form's message of an invalid e-mail address (form.TranslationKeyInvalidEmail), translated like go-form's own messages, at its field. An empty value passes; required checks that. An address go-form already refuses itself, the value of an email input (form:"input,email" or email:"true") that is no address at all, gets no second message.
Types ¶
type Describer ¶
type Describer interface {
Describe() string
}
Describer is a Sender that can say how it sends, for people who check the site's set-up, such as the admin's setup guide: "SMTP mail.example.com:587, from Site <noreply@example.com>". The description never holds a secret, such as a password or an API key. SMTP, Log and Memory implement it.
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory keeps sent messages, for tests.
type Message ¶
type Message struct {
// To are the recipients' addresses; every recipient sees them all.
To []string
// ReplyTo is where replies go instead of the sender, such as the
// visitor who filled in a contact form.
ReplyTo string
Subject string
// Text is the plain text body, which every mail program can show.
Text string
// HTML is the optional rich body, sent next to Text.
HTML string
// Headers are extra header fields, for example List-Unsubscribe and
// List-Unsubscribe-Post (RFC 8058) on newsletters. Compose refuses names
// it writes itself, such as From or Content-Type, and line breaks.
Headers map[string]string
}
Message is one e-mail. Text is required; HTML is optional.
type SMTP ¶
type SMTP struct {
// Host is the mail server's name, also checked against its
// certificate.
Host string
// Port is the server's port; 587 when zero.
Port int
// Username and Password sign in to the server; an empty Username
// sends without signing in.
Username string
Password string
// From is the sender's address, such as "Site <noreply@example.com>".
From string
// Timeout bounds the whole conversation with the server, from dialling
// to QUIT. Zero uses DefaultSMTPTimeout.
Timeout time.Duration
}
SMTP sends through a mail server, with PLAIN authentication when Username is set. STARTTLS is used when the server offers it (ports 587 and 25); implicit TLS on port 465 is not supported.
Send stops when its context ends or after Timeout, whichever comes first, so a slow or hanging mail server cannot hold the caller indefinitely.
Source Files