smtp

Documentation

Overview

Package smtp implements the platform/mail Mailer interface using SMTP.

Security rules (security-baseline.md section 3):

• Credentials are set only via SMTPConfig; never appear in URLs or query strings
• Passwords must never be logged under any circumstance
• BCC recipients are submitted to the SMTP server but are not added to visible headers
• STARTTLS is enforced when TLSPolicy is TLSRequired (the default for port 587)

Usage:

cfg := smtp.SMTPConfig{
    Host:      "smtp.example.com",
    Port:      587,
    Username:  os.Getenv("SMTP_USERNAME"),
    Password:  os.Getenv("SMTP_PASSWORD"),
    From:      "noreply@example.com",
    TLSPolicy: smtp.TLSRequired,
}

mailer, err := smtp.New(cfg)
if err != nil {
    return err
}

var m mail.Mailer = mailer

Index

• Constants
• Variables
• type Adapter
  • func New(cfg SMTPConfig) (*Adapter, error)
  • func (a *Adapter) Send(ctx context.Context, msg mail.Message) error
• type SMTPConfig
  • func (c SMTPConfig) Validate() error
• type TLSPolicy

Constants

const DefaultTimeout = 30 * time.Second

DefaultTimeout is applied when SMTPConfig.Timeout is zero.

Variables

var ErrTLSRequired = errors.New("smtp: server does not support STARTTLS but TLSPolicy is TLSRequired")

ErrTLSRequired is returned when TLSPolicy is TLSRequired but the server does not advertise the STARTTLS extension.

Types

type Adapter

type Adapter struct {
	// contains filtered or unexported fields
}

Adapter is an SMTP implementation of mail.Mailer. Safe for concurrent use; each Send call creates an independent connection.

func New

func New(cfg SMTPConfig) (*Adapter, error)

New constructs an Adapter from the provided config.

func (*Adapter) Send

func (a *Adapter) Send(ctx context.Context, msg mail.Message) error

Send delivers msg via SMTP with retry support. The message is validated before any connection is attempted. Credentials are never included in error messages or logs.

type SMTPConfig

type SMTPConfig struct {
	Host       string
	Port       int
	Username   string
	Password   string
	From       string
	Timeout    time.Duration
	MaxRetries int
	// TLSPolicy controls whether STARTTLS is required, opportunistic, or disabled.
	// Defaults to TLSRequired when zero value; set TLSOpportunistic or TLSNone
	// explicitly when a lower security posture is intentionally chosen.
	TLSPolicy TLSPolicy
	// TLSConfig is the optional TLS configuration for STARTTLS negotiation.
	// Nil uses crypto/tls defaults with ServerName set to Host.
	TLSConfig *tls.Config
}

SMTPConfig holds configuration for the SMTP adapter. Credentials must come from environment variables or a secret provider.

func (SMTPConfig) Validate

func (c SMTPConfig) Validate() error

Validate checks the SMTPConfig before use.

type TLSPolicy

type TLSPolicy int

TLSPolicy controls STARTTLS behaviour for SMTP connections.

const (
	// TLSRequired enforces STARTTLS: the connection is aborted if the server
	// does not advertise STARTTLS or if the TLS handshake fails.
	// This is the recommended setting for port 587 (submission).
	TLSRequired TLSPolicy = iota

	// TLSOpportunistic upgrades to TLS when the server advertises STARTTLS,
	// but continues in plaintext if the extension is absent.
	// Use only for legacy relay scenarios with controlled infrastructure.
	TLSOpportunistic

	// TLSNone skips STARTTLS entirely. Use only for local or test servers
	// that do not support TLS (e.g. MailHog, port 25 internal relay).
	TLSNone
)