mail

Package mail defines email messages and the Sender contract implemented by provider modules such as mail/resend and mail/smtp (ADR-0025).

Stability: pre-1.0 (ADR-0015).

Variables#

var ErrRejected#

var ErrRejected = errors.New("mail: rejected")

ErrRejected marks a send that will never succeed as it is, such as an invalid message, an unverified sender domain or a refused recipient. Providers wrap it; the jobs mail worker stops retrying such sends. Temporary failures (network errors, rate limits, provider outages) must not wrap it.

Types#

type Address#

type Address struct {
	Name  string
	Email string
}

An Address is an email address with an optional display name.

func (Address) String#

func (a Address) String() string

String formats the address for an email header, quoting the name if needed.

type Defaults#

type Defaults struct {
	FromName  config.Value[string]
	FromEmail config.Value[string]
	// ReplyTo is one email address; an empty value means no reply-to.
	ReplyTo config.Value[string]
}

Defaults are live sender values applied to messages that leave them empty. Each is read on every send, so runtime settings apply immediately. A nil field is ignored.

type Message#

type Message struct {
	From    Address
	To      []Address
	ReplyTo []Address
	Subject string
	// Text and HTML are alternative bodies; at least one is required.
	Text string
	HTML string
	// IdempotencyKey lets providers drop duplicate sends, for example when a
	// background job is retried. Jobs use their job ID.
	IdempotencyKey string
	// Tags are provider metadata such as a message category.
	Tags map[string]string
}

A Message is an email to send. Add fields by setting them; the zero value of every optional field means "not set".

func (Message) Validate#

func (m Message) Validate() error

Validate reports whether m has a sender, at least one valid recipient, a subject without line breaks and a body.

type Sender#

type Sender interface {
	Send(ctx context.Context, m Message) error
}

A Sender delivers email. Implementations must be safe for concurrent use, respect ctx cancellation and return an error when delivery fails.

func WithDefaults#

func WithDefaults(next Sender, d Defaults) Sender

WithDefaults returns a Sender that fills an empty From and ReplyTo from d, then sends through next. Messages that set them keep their own.

type SenderFunc#

type SenderFunc func(ctx context.Context, m Message) error

SenderFunc adapts a function to the Sender interface.

func (SenderFunc) Send#

func (f SenderFunc) Send(ctx context.Context, m Message) error

Send calls f(ctx, m).