smtprelay

package
v1.4.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: AGPL-3.0 Imports: 44 Imported by: 0

Documentation

Overview

Package smtprelay is the SMTP relay: apps that only speak SMTP send transactional mail through it instead of the HTTP API. It is off until an instance admin turns it on (Instance admin › Instance settings), and listens on 587 with STARTTLS and on 465 with TLS. Credentials are SMTP credentials, send-only keys of a workspace: the username is the key's ID, the password its secret. The From address must be a verified Transactional sender. Mail is logged as "Raw (SMTP)" and goes through the workspace's Transactional route, suppression rules and log.

The server is github.com/emersion/go-smtp: a maintained, dependency-light SMTP server library (go-sasl and go-message, already in the module graph through go-imap) with STARTTLS, implicit TLS, AUTH PLAIN and graceful shutdown, used by Maddy and other mail servers. Writing an SMTP server from net/textproto would duplicate that work and its edge cases.

The certificate comes from Let's Encrypt (golang.org/x/crypto's autocert, with its cache sealed in Postgres so every web node shares it and any of them answers the HTTP-01 challenge) or from files an operator manages.

Index

Constants

View Source
const (
	MaxConnections      = 500
	MaxConnectionsPerIP = 20
	// AuthFailures failed logins within AuthFailureWindow block the address
	// for AuthBlock.
	AuthFailures      = 5
	AuthFailureWindow = 10 * time.Minute
	AuthBlock         = 15 * time.Minute
)

Abuse limits of the relay (review 2026-11 TX-6): each web node caps its SMTP connections, in all and per address, and an address that keeps failing to log in is refused for a while.

View Source
const (
	HeaderTags     = "X-ReputeCast-Tags"
	HeaderCategory = "X-ReputeCast-Category"
)

Headers the relay reads and drops.

View Source
const (
	// MaxMessageBytes is the largest message the relay accepts; the route's
	// providers may accept less (the reply then says so).
	MaxMessageBytes = 40 << 20
	DefaultPoll     = 30 * time.Second
)

Limits of the relay.

Variables

This section is empty.

Functions

func Register

func Register(h huma.API, r *Relay, publicURL func(context.Context) string)

Register adds Instance admin › SMTP relay.

func RegisterJobs

func RegisterJobs(reg *jobs.Registry, r *Relay, publicURL func(context.Context) string)

RegisterJobs adds the relay's periodic status check.

Types

type CheckArgs

type CheckArgs struct{}

CheckArgs runs the relay's status checks.

func (CheckArgs) InsertOpts

func (CheckArgs) InsertOpts() river.InsertOpts

InsertOpts implements river.JobArgsWithInsertOpts.

func (CheckArgs) Kind

func (CheckArgs) Kind() string

Kind implements river.JobArgs.

type CheckWorker

type CheckWorker struct {
	river.WorkerDefaults[CheckArgs]
	R         *Relay
	PublicURL func(context.Context) string
}

CheckWorker runs CheckArgs while the relay is on.

func (*CheckWorker) Work

func (w *CheckWorker) Work(ctx context.Context, _ *river.Job[CheckArgs]) error

Work implements river.Worker.

type Config

type Config struct {
	Enabled      bool
	Hostname     string
	StartTLSPort int
	TLSPort      int
	CertSource   string // acme, files
	CertFile     string
	KeyFile      string
}

Config is how the relay listens.

type PublicURL

type PublicURL func(context.Context) string

PublicURL returns the instance's public URL (for the suggested hostname).

type Relay

type Relay struct {
	Pool   *pgxpool.Pool
	Q      *store.Queries
	Box    *secrets.Box
	Audit  *audit.Logger
	Log    *slog.Logger
	Sender Sender
	Now    func() time.Time
	// ListenHost is the address the listeners bind to ("" for every
	// interface).
	ListenHost string
	// Poll is how often a running relay reads its settings again.
	Poll time.Duration
	// Resolver and DialTimeout serve the status checks.
	Resolver    *net.Resolver
	DialTimeout time.Duration
	// RootCAs verify the certificate in the status checks (nil: the
	// system's roots).
	RootCAs *x509.CertPool
	// contains filtered or unexported fields
}

Relay runs the SMTP relay's listeners in a web process.

func (*Relay) ACMEHandler

func (r *Relay) ACMEHandler() http.Handler

ACMEHandler answers Let's Encrypt's HTTP-01 challenge for the relay's hostname (/.well-known/acme-challenge/…); the web router mounts it.

func (*Relay) Check

func (r *Relay) Check(ctx context.Context, publicURL string) (SMTPRelaySettings, error)

Check runs the status checks: the hostname resolves, both ports answer at its address (connecting from this server), and the certificate is valid. While a port doesn't answer, instance admins are told once.

func (*Relay) Listening

func (r *Relay) Listening() (Config, bool)

Listening reports the configuration the relay listens with, if any.

func (*Relay) Reconcile

func (r *Relay) Reconcile(ctx context.Context) error

Reconcile starts, restarts or stops the listeners to match the saved settings.

func (*Relay) Run

func (r *Relay) Run(ctx context.Context) error

Run keeps the relay's listeners in line with its settings until ctx ends, then stops them gracefully (sessions get a few seconds to finish).

func (*Relay) Save

func (r *Relay) Save(ctx context.Context, in SMTPRelayInput, publicURL string) (SMTPRelaySettings, error)

Save changes the relay's settings: audited as turned on, off or changed.

func (*Relay) Settings

func (r *Relay) Settings(ctx context.Context, publicURL string) (SMTPRelaySettings, error)

Settings returns the relay's settings and last status.

func (*Relay) Stop

func (r *Relay) Stop()

Stop stops the listeners at once (tests; Run stops them when its context ends).

func (*Relay) Wake

func (r *Relay) Wake()

Wake makes a running relay read its settings now (after a save).

type SMTPRelayCertificate

type SMTPRelayCertificate struct {
	NotAfter time.Time `json:"notAfter"`
	Issuer   string    `json:"issuer" example:"Let's Encrypt"`
}

SMTPRelayCertificate is the certificate the relay serves.

type SMTPRelayCheck

type SMTPRelayCheck struct {
	Key    string `json:"key" enum:"dns,starttls,tls,certificate"`
	OK     bool   `json:"ok"`
	Detail string `json:"detail" example:"reputecast.acme.io points to 203.0.113.40"`
	// Port is the port a port check connected to.
	Port int `json:"port,omitempty"`
}

SMTPRelayCheck is one status check.

type SMTPRelayInput

type SMTPRelayInput struct {
	Enabled      bool   `json:"enabled"`
	Hostname     string `json:"hostname" maxLength:"253"`
	StartTLSPort int    `json:"starttlsPort" minimum:"1" maximum:"65535" default:"587"`
	TLSPort      int    `json:"tlsPort" minimum:"1" maximum:"65535" default:"465"`
	CertSource   string `json:"certSource" enum:"acme,files" default:"acme"`
	CertFile     string `json:"certFile,omitempty" maxLength:"1024" doc:"PEM certificate chain (files)"`
	KeyFile      string `json:"keyFile,omitempty" maxLength:"1024" doc:"PEM private key (files)"`
}

SMTPRelayInput saves the relay's settings.

type SMTPRelaySettings

type SMTPRelaySettings struct {
	Enabled      bool                  `json:"enabled"`
	Hostname     string                `json:"hostname" example:"reputecast.acme.io"`
	StartTLSPort int                   `json:"starttlsPort" example:"587"`
	TLSPort      int                   `json:"tlsPort" example:"465"`
	CertSource   string                `json:"certSource" enum:"acme,files"`
	CertFile     string                `json:"certFile"`
	KeyFile      string                `json:"keyFile"`
	Certificate  *SMTPRelayCertificate `json:"certificate,omitempty"`
	// RenewError is why the last certificate request or load failed.
	RenewError    string     `json:"renewError,omitempty"`
	RenewFailedAt *time.Time `json:"renewFailedAt,omitempty"`
	EnabledBy     string     `json:"enabledBy,omitempty"`
	EnabledAt     *time.Time `json:"enabledAt,omitempty"`
	// UnreachableSince is set while a port check fails.
	UnreachableSince *time.Time      `json:"unreachableSince,omitempty"`
	Status           SMTPRelayStatus `json:"status"`
	// SuggestedHostname is the public URL's host.
	SuggestedHostname string `json:"suggestedHostname"`
}

SMTPRelaySettings is the SMTP relay section of Instance settings.

type SMTPRelayStatus

type SMTPRelayStatus struct {
	CheckedAt *time.Time       `json:"checkedAt,omitempty"`
	Checks    []SMTPRelayCheck `json:"checks"`
	// From says where the port checks ran: this server, connecting to the
	// hostname's address (no outside service is asked).
	From string `json:"from,omitempty"`
}

SMTPRelayStatus is the last status check.

type Sender

type Sender interface {
	AuthenticateSMTP(ctx context.Context, username, password string, ip *netip.Addr) (transactional.SMTPCredential, error)
	SendRaw(ctx context.Context, cred transactional.SMTPCredential, m transactional.RawMessage) ([]transactional.RawResult, error)
}

Sender authenticates SMTP credentials and queues their mail (the transactional domain).

Jump to

Keyboard shortcuts

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