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
- func Register(h huma.API, r *Relay, publicURL func(context.Context) string)
- func RegisterJobs(reg *jobs.Registry, r *Relay, publicURL func(context.Context) string)
- type CheckArgs
- type CheckWorker
- type Config
- type PublicURL
- type Relay
- func (r *Relay) ACMEHandler() http.Handler
- func (r *Relay) Check(ctx context.Context, publicURL string) (SMTPRelaySettings, error)
- func (r *Relay) Listening() (Config, bool)
- func (r *Relay) Reconcile(ctx context.Context) error
- func (r *Relay) Run(ctx context.Context) error
- func (r *Relay) Save(ctx context.Context, in SMTPRelayInput, publicURL string) (SMTPRelaySettings, error)
- func (r *Relay) Settings(ctx context.Context, publicURL string) (SMTPRelaySettings, error)
- func (r *Relay) Stop()
- func (r *Relay) Wake()
- type SMTPRelayCertificate
- type SMTPRelayCheck
- type SMTPRelayInput
- type SMTPRelaySettings
- type SMTPRelayStatus
- type Sender
Constants ¶
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.
const ( HeaderTags = "X-ReputeCast-Tags" HeaderCategory = "X-ReputeCast-Category" )
Headers the relay reads and drops.
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 ¶
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.
type CheckWorker ¶
type CheckWorker struct {
river.WorkerDefaults[CheckArgs]
R *Relay
PublicURL func(context.Context) string
}
CheckWorker runs CheckArgs while the relay is on.
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 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 ¶
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 ¶
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) Reconcile ¶
Reconcile starts, restarts or stops the listeners to match the saved settings.
func (*Relay) Run ¶
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.
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).