Documentation
¶
Overview ¶
Package mail sends outgoing email. A Message is one plain-text email to one recipient, optionally with in-memory attachments; a Sender delivers it. NewSMTPSender delivers through an SMTP server that always encrypts (except to a loopback host), and WriterSender writes the message out for development. Every sender validates and encodes a message the same way, so what WriterSender prints is what SMTP sends. See https://tangoframework.com/docs/guides/mail/.
Index ¶
Constants ¶
const DefaultMaxAttachmentSize = 10 << 20
DefaultMaxAttachmentSize is the most raw attachment bytes, all of a message's attachments together, a sender accepts unless configured otherwise: 10 MiB.
const DefaultSMTPTimeout = 30 * time.Second
DefaultSMTPTimeout bounds one SMTP exchange when Send's context has no deadline.
const SMTPURLEnv = "TANGO_SMTP_URL"
SMTPURLEnv is the environment variable SMTPSenderFromEnv reads.
Variables ¶
var ErrInvalidAttachment = errors.New("mail: invalid attachment")
ErrInvalidAttachment is returned for an attachment no sender will send: a missing filename, a control character in its filename, or a malformed content type. An error matching it also matches ErrInvalidMessage.
var ErrInvalidMessage = errors.New("mail: invalid message")
ErrInvalidMessage is returned for a message no sender will send: a missing or malformed address, or a line break in a header value.
var ErrMessageTooLarge = errors.New("mail: message too large")
ErrMessageTooLarge is returned when a message's attachments together exceed the sender's limit (see WithMaxAttachmentSize). It is a configured policy, not a malformed message, so it doesn't match ErrInvalidMessage.
var ErrNotConfigured = errors.New("mail: TANGO_SMTP_URL is not set")
ErrNotConfigured is returned by SMTPSenderFromEnv when TANGO_SMTP_URL is unset or empty.
Functions ¶
This section is empty.
Types ¶
type Attachment ¶
Attachment is one file attached to a Message, held in memory. An empty ContentType is sent as application/octet-stream.
type Message ¶
type Message struct {
From string
To string
Subject string
Text string
Attachments []Attachment
}
Message is one plain-text email to one recipient. From and To are single addresses, optionally with a display name ("Shop <noreply@example.com>").
type Option ¶
type Option func(*options)
Option configures a sender.
func WithMaxAttachmentSize ¶
WithMaxAttachmentSize sets the most raw attachment bytes, all of a message's attachments together, a sender accepts; a larger message fails with ErrMessageTooLarge. On the wire, base64 makes attachments about a third larger. The limit bounds what is sent, not memory the caller has already allocated. It panics unless n is positive.
type SMTPSender ¶
type SMTPSender struct {
// contains filtered or unexported fields
}
SMTPSender delivers mail through an SMTP server, opening one connection per message. Create one with NewSMTPSender or SMTPSenderFromEnv. It is safe for concurrent use.
func NewSMTPSender ¶
func NewSMTPSender(rawURL string, opts ...Option) (*SMTPSender, error)
NewSMTPSender returns a sender for the server rawURL names. The scheme chooses how the connection is secured:
smtp://user:pass@host:587 STARTTLS, required: a server that doesn't offer it is refused smtps://user:pass@host:465 TLS from the first byte smtp+insecure://localhost:1025 plaintext, for a local tool such as Mailpit
smtp+insecure is accepted only for a loopback host (localhost or a loopback IP), never with credentials, and only with an explicit port, so plaintext is always a deliberate choice. smtp and smtps default to ports 587 and 465. Credentials, if any, are sent with AUTH PLAIN. Errors never contain the URL, so a password can't leak into logs.
func SMTPSenderFromEnv ¶
func SMTPSenderFromEnv(opts ...Option) (*SMTPSender, error)
SMTPSenderFromEnv returns NewSMTPSender for TANGO_SMTP_URL, or ErrNotConfigured when it is unset or empty.
func (*SMTPSender) Send ¶
func (s *SMTPSender) Send(ctx context.Context, message Message) error
Send validates message, then delivers it in one SMTP exchange bounded by ctx's deadline, or DefaultSMTPTimeout when ctx has none. A server's refusal is reported by stage and reply code only: its text can echo whatever the client sent.
type Sender ¶
Sender delivers a Message. Send is synchronous and truthful: it returns nil only once the message has been handed on, and otherwise the error that stopped it. An invalid message fails with ErrInvalidMessage before anything is sent. Send must return promptly once ctx is done: callers such as accounts' outbox rely on it to finish within a shutdown deadline.
func WriterSender ¶
WriterSender returns a Sender that writes each message to w in the exact wire format an SMTP sender would send, for development. Choose it explicitly, for example with os.Stdout: nothing in tanGO falls back to it. Messages carry live links and attachment data, so don't point it at production logs.
Source Files
Directories