mailer

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Overview

Package mailer is the service's work: the smtp.Send activity that queues a mail, the Route hook an installation may bind to pick the account, the delivery itself when the queue hands it back, the events and audit records of every outcome, and the suppressor reacting to permanent failures.

Index

Constants

View Source
const (
	OutcomeQueued     = "queued"
	OutcomeSent       = "sent"
	OutcomeFailed     = "failed"
	OutcomeSuppressed = "suppressed"
)

Outcomes of a delivery, as idempotency keeps them and audit names them.

View Source
const (
	ReasonRecipientRejected = "recipient_rejected"
	ReasonRejected          = "rejected"
	ReasonInvalid           = "invalid"
	ReasonExhausted         = "exhausted"
	ReasonSuppressed        = "suppressed"
)

Reasons of a failure.

View Source
const SuppressorConsumer = "smtp-failed-suppressor"

SuppressorConsumer is the reactor's pinned consumer name.

Variables

View Source
var (
	ErrUnknownAccount = accounts.ErrUnknownAccount
	ErrRoute          = errors.New("mailer: route hook failed")
)

Errors of Send.

Functions

This section is empty.

Types

type Failed

type Failed struct {
	ID        string   `json:"id"`
	Account   string   `json:"account"`
	To        []string `json:"to"`
	Error     string   `json:"error"`
	Reason    string   `json:"reason"`
	Permanent bool     `json:"permanent"`
	Attempts  int      `json:"attempts"`
}

Failed: the mail will not be delivered (permanent) or an attempt failed and the queue retries (not permanent: only logged).

type Mailer

type Mailer struct {
	deps.Component

	Route hook.Ref[RouteIn, RouteOut]
	// contains filtered or unexported fields
}

Mailer is the component.

func New

func New(
	parent deps.Scope, st deps.Dependency[*store.Store], acc *accounts.Accounts, set Settings, queue outbox.Config,
	instance string,
) (*Mailer, error)

New declares everything under parent.

func (*Mailer) Dead

func (m *Mailer) Dead(ctx context.Context, d outbox.Delivery, attempts int, lastError string)

Dead: the queue gave up on d.

func (*Mailer) Deliver

func (m *Mailer) Deliver(ctx context.Context, d outbox.Delivery, attempt int) error

Deliver is what the queue calls: builds the MIME and hands it to the account. Its error decides the queue's next step.

func (*Mailer) Failed

func (m *Mailer) Failed() event.Ref[Failed]

func (*Mailer) Queue added in v0.2.0

func (m *Mailer) Queue() *outbox.Outbox

Events the mailer raises. Queue is the outbox, for the console's requeue.

func (*Mailer) Send

func (m *Mailer) Send(ctx context.Context, msg mail.Message) (SendResult, error)

Send is the smtp.Send activity: checks the message, drops suppressed recipients, picks the account, and queues the delivery once per key.

func (*Mailer) Sent

func (m *Mailer) Sent() event.Ref[Sent]

func (*Mailer) Settings added in v0.2.0

func (m *Mailer) Settings() Settings

Settings as the mailer runs with them (live fields read when asked).

func (*Mailer) Suppress

func (m *Mailer) Suppress(ctx context.Context, address, reason, detail string) error

Suppress adds a suppression by hand (the console, tests).

func (*Mailer) Suppressed

func (m *Mailer) Suppressed() event.Ref[Suppressed]

type RouteIn

type RouteIn struct {
	Account    string   `json:"account,omitempty" schemapb:"description=What the message asked for"`
	From       string   `json:"from,omitempty"`
	To         []string `json:"to"`
	Subject    string   `json:"subject"`
	Candidates []string `json:"candidates"        schemapb:"description=Configured accounts"`
}

RouteIn asks the installation which account carries the message.

type RouteOut

type RouteOut struct {
	Account string `json:"account"`
	From    string `json:"from,omitempty"`
}

RouteOut: the account, and the sender to use.

type SendResult

type SendResult struct {
	ID      string `json:"id"      schemapb:"description=Delivery id, the mail's Message-ID"`
	Status  string `json:"status"  schemapb:"description=queued or suppressed, or the outcome of a repeated key"`
	Account string `json:"account"`
	// Suppressed recipients were dropped from the message.
	Suppressed []string `json:"suppressed,omitempty"`
	// Duplicate: the idempotency key was seen; nothing new was queued.
	Duplicate bool `json:"duplicate,omitempty"`
}

SendResult is smtp.Send's answer.

type Sent

type Sent struct {
	ID        string   `json:"id"`
	Account   string   `json:"account"`
	MessageID string   `json:"message_id"`
	To        []string `json:"to"`
	Attempt   int      `json:"attempt"`
	DryRun    bool     `json:"dry_run,omitempty"`
}

Sent: the relay accepted the mail.

type Settings

type Settings struct {
	Limits         mail.Limits
	IdempotencyTTL time.Duration
	SuppressionTTL time.Duration
	// Live: the account used when the message names none and no Route
	// binding answers.
	DefaultAccount config.Live[string]
	// Live: accept and record, send nothing.
	DryRun config.Live[bool]
	// Live: honor suppressions.
	Suppressions config.Live[bool]
}

Settings of the mailer: what the service configuration decides.

type Suppressed

type Suppressed struct {
	ID      string   `json:"id"`
	Account string   `json:"account"`
	To      []string `json:"to"`
}

Suppressed: every recipient was suppressed, nothing was queued.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL