mailbox

package
v1.3.1 Latest Latest
Warning

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

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

Documentation

Overview

Package mailbox decides which mailbox provider filters an address's mail.

Consumer domains (gmail.com, outlook.com, yahoo.co.jp…) are known by name. A company's own domain is classified from its MX records: Google Workspace mail is filtered by Gmail, Microsoft 365 by Outlook (Exchange Online Protection), Yahoo-hosted domains by Yahoo and iCloud+ custom domains by iCloud. The answer is kept on the contact (mailbox_provider, mailbox_detail, mailbox_checked_at), so routing conditions, per-mailbox throttles, the auto-pause guard, warm-up and reports all agree on it.

Index

Constants

View Source
const (
	Gmail   = emailaddr.Gmail
	Outlook = emailaddr.Outlook
	Yahoo   = emailaddr.Yahoo
	ICloud  = emailaddr.ICloud
	Other   = emailaddr.Other
)

Mailbox provider keys, as stored on contacts and messages.

View Source
const NotReported = "not_reported"

NotReported is the reason an API gives for a complaint rate it leaves empty because the mailbox provider doesn't report complaints.

Variables

Providers lists the keys in chart order.

Functions

func Name

func Name(provider string) string

Name is a mailbox provider's display name.

func ReportsComplaints

func ReportsComplaints(provider string) bool

ReportsComplaints reports whether a mailbox provider tells senders about each complaint (a feedback loop: Outlook.com's JMRP, Yahoo's CFL and the ISPs behind "other"). Gmail and Apple never do: Gmail's spam rate comes only as a daily aggregate in Postmaster Tools. A complaint rate measured over their delivered mail would read 0% whatever readers did, so rates leave their mail out and their own rate is "not reported".

Types

type Class

type Class struct {
	Provider string `json:"provider"`
	// Detail names the hosting of a company domain; empty for consumer
	// domains and for domains whose hosting isn't recognised.
	Detail string `json:"detail,omitempty"`
}

Class is the mailbox provider that filters a domain's mail and, for a company domain, the hosting behind it ("Google Workspace").

func FromHosting

func FromHosting(domain, hosting string) Class

FromHosting classifies a domain whose MX hosting is known (see emailaddr.HostingFromMX). Consumer domains keep their provider.

func Static

func Static(domain string) Class

Static classifies a domain by name only: consumer domains get their provider, every other domain is Other until its MX records are known.

func (Class) Hosted

func (c Class) Hosted() bool

Hosted reports whether the domain is a company's own, hosted by a mailbox provider.

type Classifier

type Classifier struct {
	Q    *store.Queries
	MX   *MXChecker
	Jobs func() *jobs.Client
	Log  *slog.Logger
	// contains filtered or unexported fields
}

Classifier keeps contacts' mailbox providers right for company domains.

Contacts are added with the provider their domain's name gives (every insert path does that); a company domain starts as Other. The sweep job looks those domains up and applies the answer to every contact on them, and the send paths call ClassifyPending first so a fresh import is routed, throttled and guarded by its real mailbox provider. Addresses that aren't contacts (transactional recipients, the route tester) are classified with ForEmail from the cache, looking a new domain up in the background.

func (*Classifier) ClassifyPending

func (c *Classifier) ClassifyPending(ctx context.Context, workspaceID uuid.UUID, budget time.Duration) (int64, error)

ClassifyPending classifies the workspace's contacts whose company domain was never looked up, until done or budget runs out (a send's audience is then built from the answers; what's left keeps Other and is picked up by the sweep). It returns how many contacts changed.

func (*Classifier) ForEmail

func (c *Classifier) ForEmail(ctx context.Context, email string) Class

ForEmail classifies an address. Consumer domains answer at once; a company domain comes from the MX cache, and a domain never seen is looked up in the background while this call answers Other.

func (*Classifier) Sweep

func (c *Classifier) Sweep(ctx context.Context, budget time.Duration, maxDomains int) (int64, error)

Sweep classifies waiting contacts across workspaces, at most maxDomains domains or budget.

type LookupArgs

type LookupArgs struct {
	Domain string `json:"domain"`
}

LookupArgs asks for one domain's classification.

func (LookupArgs) Kind

func (LookupArgs) Kind() string

Kind implements river.JobArgs.

type LookupWorker

type LookupWorker struct {
	river.WorkerDefaults[LookupArgs]
	C *Classifier
}

LookupWorker looks a domain up and applies it to waiting contacts.

func (*LookupWorker) Work

func (w *LookupWorker) Work(ctx context.Context, j *river.Job[LookupArgs]) error

Work implements river.Worker.

type MXChecker

type MXChecker struct {
	Q        *store.Queries
	Resolver Resolver
	TTL      time.Duration
	// Timeout bounds one lookup; Parallel bounds concurrent lookups.
	Timeout  time.Duration
	Parallel int
}

MXChecker tells whether a domain accepts mail and who hosts it, caching answers in mx_cache for a week so imports and the classifier don't hit DNS again for the same domain.

func (*MXChecker) Check

func (m *MXChecker) Check(ctx context.Context, domains []string) (map[string]MXResult, error)

Check returns, for each domain, whether it can receive mail. Temporary DNS failures count as "yes": an address is only rejected for a definite answer (NXDOMAIN, or no MX and no address records).

type MXResult

type MXResult struct {
	HasMX bool
	// Hosting names the mailbox hosting behind an "other" domain
	// ("Google Workspace"), from the MX host.
	Hosting string
	// Checked is false when DNS gave no definite answer (a timeout or a
	// server failure): HasMX is then a benign "yes" and Hosting unknown.
	Checked bool
}

MXResult is what a domain's DNS says.

type Resolver

type Resolver interface {
	LookupMX(ctx context.Context, name string) ([]*net.MX, error)
	LookupHost(ctx context.Context, host string) ([]string, error)
}

Resolver is the part of net.Resolver the MX check uses.

type SweepArgs

type SweepArgs struct{}

SweepArgs is the periodic sweep.

func (SweepArgs) InsertOpts

func (SweepArgs) InsertOpts() river.InsertOpts

InsertOpts runs the sweep on the maintenance queue, one at a time.

func (SweepArgs) Kind

func (SweepArgs) Kind() string

Kind implements river.JobArgs.

type SweepWorker

type SweepWorker struct {
	river.WorkerDefaults[SweepArgs]
	C *Classifier
}

SweepWorker classifies waiting contacts in the background.

func (*SweepWorker) Work

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

Work implements river.Worker.

Jump to

Keyboard shortcuts

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