Documentation
¶
Overview ¶
Package mail provides a Mailer abstraction with an SMTP driver modelled on Laravel's Mail facade.
Two primitives:
- Message — the email payload (From/To/Cc/Bcc/Subject/Text/HTML + attachments). Built by hand or via NewMessage(...).
- Mailer — the transport interface. The bundled SMTPMailer talks to any RFC-compliant SMTP server (Postfix, Sendgrid, Mailgun, Postmark, AWS SES, Mailtrap, MailHog).
A LogMailer is shipped for tests/local dev — it captures sent messages in memory instead of delivering them.
Usage:
m := mail.NewSMTPMailer(mail.SMTPConfig{
Host: "smtp.mailgun.org",
Port: 587,
Username: "postmaster@example.com",
Password: os.Getenv("MAIL_PASSWORD"),
From: "noreply@example.com",
})
err := m.Send(ctx, mail.NewMessage().
To("user@example.com").
Subject("Hello").
HTML("<h1>Hi!</h1>").
Build())
Index ¶
- Variables
- type Attachment
- type Builder
- func (b *Builder) Attach(filename string, data []byte, contentType ...string) *Builder
- func (b *Builder) Bcc(addrs ...string) *Builder
- func (b *Builder) Build() Message
- func (b *Builder) Cc(addrs ...string) *Builder
- func (b *Builder) From(addr string) *Builder
- func (b *Builder) HTML(s string) *Builder
- func (b *Builder) Header(k, v string) *Builder
- func (b *Builder) ReplyTo(addr string) *Builder
- func (b *Builder) Subject(s string) *Builder
- func (b *Builder) Text(s string) *Builder
- func (b *Builder) To(addrs ...string) *Builder
- type LogMailer
- type Mailer
- type Message
- type SMTPConfig
- type SMTPMailer
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyRecipients = errors.New("mail: at least one recipient required")
ErrEmptyRecipients is returned when a Message has no To/Cc/Bcc.
var ErrHeaderInjection = errors.New("mail: CR/LF in header field rejected")
ErrHeaderInjection is returned when an address or header value contains a CR/LF, which could be used to smuggle additional headers (e.g. a hidden Bcc) into the RFC 5322 header block.
Functions ¶
This section is empty.
Types ¶
type Attachment ¶
type Attachment struct {
Filename string
ContentType string // e.g. "image/png"; auto-detected from extension when empty
Data []byte
}
Attachment is an inline file attached to a Message.
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder constructs a Message fluently.
type LogMailer ¶
type LogMailer struct {
Sent []Message
// contains filtered or unexported fields
}
LogMailer is an in-memory Mailer for tests/local dev. Sent messages accumulate in Sent.
type Message ¶
type Message struct {
From string
To []string
Cc []string
Bcc []string
ReplyTo string
Subject string
Text string
HTML string
Headers map[string]string
Attachments []Attachment
}
Message is an immutable email payload built via Builder.
func (Message) Encode ¶
Encode renders the Message as a complete RFC 5322 email body (including headers + MIME multipart structure). The result is suitable for the DATA portion of an SMTP exchange.
Structure:
- no attachments, text only → text/plain
- no attachments, html only → text/html
- no attachments, both → multipart/alternative
- any attachments → multipart/mixed wrapping alternative-or-single body
func (Message) Recipients ¶
Recipients returns every To/Cc/Bcc address (the envelope set).
type SMTPConfig ¶
type SMTPConfig struct {
Host string // e.g. "smtp.mailgun.org"
Port int // 25 / 465 / 587
Username string
Password string
// From is the default From address used when Message.From is empty.
From string
// Insecure disables STARTTLS. Use only with isolated dev servers
// like MailHog. The default (false) uses STARTTLS when offered.
Insecure bool
// TLSImplicit forces an immediate TLS handshake (port 465 mode).
TLSImplicit bool
}
SMTPConfig configures an SMTP-backed Mailer.
type SMTPMailer ¶
type SMTPMailer struct {
// contains filtered or unexported fields
}
SMTPMailer talks plain-text SMTP with optional STARTTLS.
func NewSMTPMailer ¶
func NewSMTPMailer(cfg SMTPConfig) *SMTPMailer
NewSMTPMailer returns a Mailer that talks to an SMTP server.
func (*SMTPMailer) Send ¶
func (m *SMTPMailer) Send(ctx context.Context, msg Message) error
Send dispatches msg. If Message.From is empty, the config's default From is used. The wall-clock deadline is taken from ctx.
Send returns as soon as ctx is done, but because net/smtp.SendMail is not context-aware the underlying delivery goroutine keeps running until the SMTP exchange finishes (or the dialler's own timeout fires) — it is not killed when ctx is cancelled. Set a Dialer/Host timeout at the network layer to bound that goroutine.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package mailgun implements mail.Mailer against Mailgun's HTTP API (https://documentation.mailgun.com/en/latest/api-sending.html).
|
Package mailgun implements mail.Mailer against Mailgun's HTTP API (https://documentation.mailgun.com/en/latest/api-sending.html). |
|
Package sendgrid implements mail.Mailer against SendGrid's v3 HTTP API (https://docs.sendgrid.com/api-reference/mail-send/mail-send).
|
Package sendgrid implements mail.Mailer against SendGrid's v3 HTTP API (https://docs.sendgrid.com/api-reference/mail-send/mail-send). |