readiness

package
v1.0.1 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 38 Imported by: 0

Documentation

Overview

Package readiness is Send Readiness (spec 5.1, 7.5): every check a campaign must pass before it goes out, each Pass, Warn, Block or Unknown with its evidence and a fix, plus the estimates around the send (final audience, route, cost and duration, throttling per mailbox provider).

A run gathers facts from the other domains and Assemble turns them into checks. Assemble is pure, so the demo seeds runs through it and tests feed it fixtures. Runs are stored in readiness_runs; the run in progress is in readiness_progress so the review screen can tick the groups in.

Index

Constants

View Source
const (
	UnengagedWarnShare = 1.0
	UnengagedWarnCount = 500
)

UnengagedWarnShare and UnengagedWarnCount decide when unengaged contacts are worth a warning: 1% of the audience or 500 contacts.

View Source
const (
	VerdictReady    = "ready"
	VerdictWarnings = "warnings"
	VerdictBlocked  = "blocked"
)

Verdicts.

View Source
const (
	Pass    = "pass"
	Warn    = "warn"
	Block   = "block"
	Unknown = "unknown"
)

Check statuses.

View Source
const (
	GroupReputation     = "reputation"
	GroupAuthentication = "authentication"
	GroupContent        = "content"
	GroupLinks          = "links"
	GroupCompliance     = "compliance"
	GroupAudience       = "audience"
	GroupRouting        = "routing"
)

Check groups, in the order of the checklist.

View Source
const (
	TriggerManual   = "manual"
	TriggerComposer = "composer"
	TriggerSchedule = "schedule"
	TriggerSendTime = "send_time"
	TriggerApproval = "approval"
)

Triggers of a run (readiness_runs.trigger).

View Source
const (
	FixExcludeSunset = "exclude_sunset"
	FixRouteOnly     = "route_only"
	FixInsertFooter  = "insert_footer"
	FixReplaceLink   = "replace_link"
	FixUseSubject    = "use_subject"
	FixMinify        = "minify"
)

Fix actions applied by POST …/readiness/fixes.

Variables

View Source
var DefaultMailboxRates = map[string]float64{"gmail": 0, "outlook": 5, "yahoo": 4, "icloud": 3, "other": 0}

DefaultMailboxRates are the per-mailbox-provider throttles: Outlook, Yahoo and iCloud accept slower streams more reliably; Gmail and the rest take each provider's full rate. The sending engine adapts them when deferrals rise.

View Source
var ErrRunning = errors.New("send readiness is already running for this campaign")

ErrRunning means a run of the campaign is already in progress.

Groups lists the check groups in checklist order.

View Source
var MailboxOrder = []string{"gmail", "outlook", "yahoo", "icloud", "other"}

MailboxOrder is the chart order of mailbox providers.

View Source
var URIBlocklists = []string{"SURBL", "URIBL", "Spamhaus DBL"}

URIBlocklists are the URI blocklists link domains are checked on.

Functions

func Clock

func Clock(t, now time.Time, loc *time.Location) string

Clock formats a time in the workspace zone: "09:40" today, "Mon 12 Oct, 09:40" on another day.

func Count

func Count(n int64) string

Count formats n with thousands separators.

func EncodeResult

func EncodeResult(res ReadinessResult) (checks, estimates json.RawMessage, err error)

EncodeResult is the stored form of a result: readiness_runs.checks (verdict, counts, groups and checks) and readiness_runs.estimates.

func Fingerprint

func Fingerprint(c store.ReadinessCampaignRow, routing json.RawMessage) string

Fingerprint identifies what a run checks: content, sender, audience, route override, the Broadcasts routing rules and the schedule. Any change to them makes the latest run stale.

func GroupTitle

func GroupTitle(g string) string

GroupTitle is the heading of a check group ("Audience quality").

func InsertFooter

func InsertFooter(src, address string) (string, bool)

InsertFooter adds the footer block at the end of the MJML body, or puts the composer's footer block back as new when it lost its address or links.

func JoinAnd

func JoinAnd(items []string) string

JoinAnd joins words as "A, B and C".

func MailboxName

func MailboxName(k string) string

MailboxName is the display name of a mailbox provider key.

func Minutes

func Minutes(seconds float64) int

Minutes rounds a duration in seconds up to whole minutes (at least 1 when anything is sent).

func Money

func Money(v float64) string

Money formats US dollars: "$2.84".

func Pct

func Pct(v float64) string

Pct formats a percentage with up to two decimals, trailing zeros trimmed: 0.6 → "0.6%", 0.04 → "0.04%", 5 → "5%".

func Pct1

func Pct1(v float64) string

Pct1 formats a percentage with one decimal: "3.1%".

func Per1000

func Per1000(v float64) string

Per1000 formats a metered price: "$0.10 per 1,000".

func Plural

func Plural(n int64, one, many string) string

Plural picks the singular or plural form.

func Rate

func Rate(v float64) string

Rate formats messages per second: "14 /s", "2.5 /s".

func Register

func Register(h huma.API, s *Service)

Register adds the readiness operations.

func ReplaceLink(src, from, to string) (string, int)

ReplaceLink points every link to from at to.

func RoutingKey

func RoutingKey(ctx context.Context, q *store.Queries, wsID uuid.UUID) json.RawMessage

RoutingKey is the Broadcasts routing as it stands, part of a run's fingerprint.

func RunningText

func RunningText(g string) string

RunningText is what a group shows while its checks run, before facts exist.

func ThresholdsLine

func ThresholdsLine(t ReadinessThresholds) string

ThresholdsLine is "bounce 2.0% · complaint 0.10%".

Types

type AfterChange

type AfterChange func(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID)

AfterChange is told when a fix or a send setting changed the campaign (the approvals domain re-checks open approvals).

type AudienceDef

type AudienceDef struct {
	Lists           []string `json:"lists,omitempty"`
	Segments        []string `json:"segments,omitempty"`
	ExcludeLists    []string `json:"exclude_lists,omitempty"`
	ExcludeSegments []string `json:"exclude_segments,omitempty"`
	ExcludeTiers    []string `json:"exclude_tiers,omitempty"`
	// IncludeSunset is the campaign overriding the sunset policy: contacts
	// whose Broadcasts the policy stopped receive this one anyway.
	IncludeSunset bool `json:"include_sunset,omitempty"`
}

AudienceDef is campaigns.audience as stored by the composer, plus the tiers Send Readiness can exclude.

func ParseAudience

func ParseAudience(raw json.RawMessage) AudienceDef

ParseAudience reads a stored audience definition.

func (AudienceDef) Empty

func (a AudienceDef) Empty() bool

Empty reports whether the definition selects nobody.

func (AudienceDef) ExcludesSunset

func (a AudienceDef) ExcludesSunset() bool

ExcludesSunset reports whether the sunset tier is excluded.

type AudienceFacts

type AudienceFacts struct {
	// BaseLabel names the audience ("Weekly Digest list", "All subscribers").
	BaseLabel string
	// GroupLabel is the caption of the audience-quality group ("Weekly Digest").
	GroupLabel string
	Lists      []string
	// Base counts the subscribed contacts of the lists and segments (minus
	// excluded lists and segments).
	Base       int64
	Suppressed int64
	Role       int64
	Duplicates int64
	// Stopped counts contacts the sunset policy stopped Broadcasts to.
	Stopped int64
	// SunsetOverride is true when the campaign overrides the sunset policy;
	// StoppedIncluded counts the stopped contacts it sends to anyway.
	SunsetOverride  bool
	StoppedIncluded int64
	// SunsetExcluded counts the sunset-tier contacts removed because the
	// campaign excludes that tier; UnengagedExcluded says it does.
	SunsetExcluded    int64
	UnengagedExcluded bool
	Final             int64
	// Unengaged counts final recipients with no open or click in
	// UnengagedDays days (the sunset tier).
	Unengaged     int64
	UnengagedDays int
	// RecentlyBounced counts final recipients who bounced in the last 30
	// days without being suppressed (soft bounces).
	RecentlyBounced int64
	// Mailboxes counts final recipients per mailbox provider.
	Mailboxes map[string]int64
	// Empty is true when the campaign has no audience yet.
	Empty bool
	// SegmentsSkipped is true when segments couldn't be counted.
	SegmentsSkipped bool
}

AudienceFacts are the audience counts after exclusions.

type AuthFacts

type AuthFacts struct {
	Domain string
	// Checked is false until deliverability has checked the domain.
	Checked   bool
	CheckedAt *time.Time
	SPFRecord string
	SPF       []ProviderAuthFacts
	DKIM      []ProviderAuthFacts
	MailFrom  []ProviderAuthFacts
	// DMARC: status (pass, missing, invalid), policy, the record and the
	// share of aligned mail over the last 7 days (nil without reports).
	DMARCStatus  string
	DMARCPolicy  string
	DMARCRecord  string
	DMARCAligned *float64
	// BIMIStatus is pass, missing or invalid.
	BIMIStatus string
}

AuthFacts are the authentication results of the sending domain.

type CampaignFacts

type CampaignFacts struct {
	ID        string
	Name      string
	Subject   string
	Preheader string
	Version   int
	// CompiledAt is when the content was last compiled (saved).
	CompiledAt *time.Time
	SenderName string
	// SenderEmail is the From address; SenderDomain its domain.
	SenderEmail  string
	SenderDomain string
	// StartAt is when the send would start (the schedule, or now).
	StartAt time.Time
	// ScheduleMode is now, at or best_time.
	ScheduleMode string
}

CampaignFacts describes the campaign being checked.

type ComplianceFacts

type ComplianceFacts struct {
	// UnsubscribeURL is the one-click unsubscribe link with a {token} placeholder.
	UnsubscribeURL string
	HTTPS          bool
	// ComplaintRate is the route's 7-day complaint rate in percent.
	ComplaintRate *float64
}

ComplianceFacts are what the bulk-sender rules need.

type ContentFacts

type ContentFacts struct {
	Report contentcheck.ContentCheckReport
	// Checked is false when the content check couldn't run.
	Checked bool
	// FooterRemovedAt is when the version without a footer was saved.
	FooterRemovedAt *time.Time
	// Address is the postal address of the workspace branding.
	Address string
	// InlineCSSBytes is the size of the inline style attributes.
	InlineCSSBytes int
	// URIBlocklists are the lists link domains were checked on.
	URIBlocklists []string
	// OwnDomain is the registrable domain of the sending domain ("acme.io").
	OwnDomain string
}

ContentFacts are the composer's content and link checks.

type Deliverability

type Deliverability interface {
	Overview(ctx context.Context, ws *store.Workspace) (deliverability.DeliverabilityOverview, error)
	Reputation(ctx context.Context, ws *store.Workspace) (deliverability.DeliverabilityReputation, error)
}

Deliverability is what a run reads from the deliverability domain: blocklist results, authentication and provider account health.

type Facts

type Facts struct {
	Now time.Time
	// Location is the workspace time zone (clock times in the evidence).
	Location *time.Location
	// Workspace is the slug, for links to other screens.
	Workspace string

	Campaign   CampaignFacts
	Audience   AudienceFacts
	Route      RouteFacts
	Reputation ReputationFacts
	Auth       AuthFacts
	Content    ContentFacts
	Compliance ComplianceFacts
	// MailboxRates are the per-mailbox-provider throttles (messages per
	// second, 0 = full rate).
	MailboxRates map[string]float64
}

Facts is everything a run looked at. Gather collects them from the other domains; the demo and tests build them by hand. Assemble turns them into the checklist and the estimates.

type ListingFacts

type ListingFacts struct {
	Asset     string
	Type      string // domain, ip
	Source    string
	Impact    string // high, medium, low
	Detail    string
	DelistURL string
	Since     *time.Time
}

ListingFacts is one asset on one blocklist.

type ProviderAuthFacts

type ProviderAuthFacts struct {
	Short string
	// OK is true when the record is verified (and aligned, for MAIL FROM).
	OK bool
	// Detail: "3 Easy DKIM CNAMEs verified", "selector postal-2026 verified",
	// the MAIL FROM domain, or what's wrong.
	Detail  string
	KeyBits int
	Domain  string
}

ProviderAuthFacts is one provider's record of one kind.

type ReadinessAudience

type ReadinessAudience struct {
	Rows  []ReadinessAudienceRow `json:"rows"`
	Final int64                  `json:"final"`
	// Lists names the lists and segments of the audience.
	Lists []string `json:"lists"`
	// Suppressed, Role and Duplicates repeat the excluded counts for the
	// confirmation ("331 suppressed · 27 role · 26 duplicates").
	Suppressed int64 `json:"suppressed"`
	Role       int64 `json:"role"`
	Duplicates int64 `json:"duplicates"`
	Unengaged  int64 `json:"unengaged"`
	// UnengagedExcluded is true when the sunset tier is excluded.
	UnengagedExcluded bool `json:"unengagedExcluded"`
}

ReadinessAudience is the final count after exclusions.

type ReadinessAudienceRow

type ReadinessAudienceRow struct {
	Label string `json:"label"`
	Count int64  `json:"count"`
	// Kind: base (the lists or segments), minus (excluded), plus (added back).
	Kind string `json:"kind" enum:"base,minus,plus"`
}

ReadinessAudienceRow is one line of the audience card.

type ReadinessCampaignPath

type ReadinessCampaignPath struct {
	api.WorkspaceInput
	CampaignID string `path:"campaignId" format:"uuid"`
}

ReadinessCampaignPath is the {workspace}/{campaignId} of readiness operations.

func (ReadinessCampaignPath) ID

func (in ReadinessCampaignPath) ID() (uuid.UUID, error)

ID parses the campaign id (404 when it isn't one).

type ReadinessCheck

type ReadinessCheck struct {
	// Key identifies the check: "audience.unengaged", "reputation.provider.ses".
	Key    string `json:"key"`
	Group  string `json:"group" enum:"reputation,authentication,content,links,compliance,audience,routing"`
	Status string `json:"status" enum:"pass,warn,block,unknown"`
	// Title states the finding; FlatTitle is the same finding prefixed with
	// its group, for lists ordered by severity ("Links: go.acme-promo.link…").
	Title     string `json:"title"`
	FlatTitle string `json:"flatTitle"`
	// Detail is the evidence. Mono is true when it is a record or a header.
	Detail string `json:"detail,omitempty"`
	Mono   bool   `json:"mono,omitempty"`
	// Label names the check in compact tables ("URL shortener"); Evidence is
	// a one-sentence version of title and detail for them.
	Label    string `json:"label,omitempty"`
	Evidence string `json:"evidence,omitempty"`
	// Short is the passing finding in a few words, used in group summaries.
	Short string `json:"short,omitempty"`
	// Ack is the sentence a person confirms before sending with this warning
	// ("I understand 412 unengaged contacts are included.").
	Ack string `json:"ack,omitempty"`
	// Note is a short right-aligned note ("timed out").
	Note  string         `json:"note,omitempty"`
	Fixes []ReadinessFix `json:"fixes"`
}

ReadinessCheck is one row of the checklist.

type ReadinessCounts

type ReadinessCounts struct {
	Passed   int `json:"passed"`
	Warnings int `json:"warnings"`
	Blocks   int `json:"blocks"`
	Unknown  int `json:"unknown"`
	Total    int `json:"total"`
}

ReadinessCounts adds up the checks.

type ReadinessEstimates

type ReadinessEstimates struct {
	Audience   ReadinessAudience   `json:"audience"`
	Route      ReadinessRoute      `json:"route"`
	Throttling []ReadinessThrottle `json:"throttling"`
}

ReadinessEstimates are the numbers around the send.

type ReadinessFix

type ReadinessFix struct {
	Kind   string            `json:"kind" enum:"apply,link"`
	Action string            `json:"action,omitempty" enum:"exclude_sunset,route_only,insert_footer,replace_link,use_subject,minify"`
	Label  string            `json:"label"`
	Tone   string            `json:"tone,omitempty" enum:"primary,danger"`
	Href   string            `json:"href,omitempty"`
	Params map[string]string `json:"params,omitempty"`
}

ReadinessFix is one fix offered with a check: an action ReputeCast applies in one click (Kind "apply", Action and Params) or a link to the screen where it's fixed (Kind "link", Href is an app path).

type ReadinessFixOutcome

type ReadinessFixOutcome struct {
	ReadinessFixResult
	Run *ReadinessRun `json:"run,omitempty"`
}

ReadinessFixOutcome is the result of applying fixes and the run after them.

type ReadinessFixRequest

type ReadinessFixRequest struct {
	Action string            `json:"action" enum:"exclude_sunset,route_only,insert_footer,replace_link,use_subject,minify"`
	Params map[string]string `json:"params,omitempty"`
}

ReadinessFixRequest is one fix to apply.

type ReadinessFixResult

type ReadinessFixResult struct {
	// Applied are the fix labels in the product voice ("Excluded 412 unengaged contacts").
	Applied []string `json:"applied"`
	// Version is the campaign version after content fixes.
	Version int `json:"version"`
}

ReadinessFixResult says what changed.

type ReadinessFixesInput

type ReadinessFixesInput struct {
	Fixes []ReadinessFixRequest `json:"fixes" minItems:"1" maxItems:"10"`
}

ReadinessFixesInput applies one or more fixes ("Apply all 3 fixes").

type ReadinessGroup

type ReadinessGroup struct {
	Key     string `json:"key" enum:"reputation,authentication,content,links,compliance,audience,routing"`
	Title   string `json:"title"`
	Caption string `json:"caption"`
	Status  string `json:"status" enum:"pass,warn,block,unknown"`
	Passed  int    `json:"passed"`
	Total   int    `json:"total"`
	// Summary is "SPF, DKIM, DMARC p=quarantine and custom MAIL FROM verified for SES".
	Summary string `json:"summary"`
	// Running describes the group while it runs ("checking 203.0.113.25 and
	// news.acme.io on 84 sources").
	Running string `json:"running"`
}

ReadinessGroup is a group heading with its caption and a summary of what passed (the collapsed "Passed" list and the running state show it).

type ReadinessHeldMove

type ReadinessHeldMove struct {
	From       string  `json:"from"`
	To         string  `json:"to"`
	ToID       string  `json:"toId"`
	AddCost    float64 `json:"addCost"`
	AddMinutes int     `json:"addMinutes"`
}

ReadinessHeldMove is what moving a held share to an available provider costs.

type ReadinessProgress

type ReadinessProgress struct {
	RunID     string                   `json:"runId"`
	Trigger   string                   `json:"trigger"`
	StartedAt time.Time                `json:"startedAt"`
	StartedBy string                   `json:"startedBy,omitempty"`
	Done      int                      `json:"done"`
	Total     int                      `json:"total"`
	Groups    []ReadinessProgressGroup `json:"groups"`
}

ReadinessProgress is a run in progress.

type ReadinessProgressGroup

type ReadinessProgressGroup struct {
	Key     string `json:"key" enum:"reputation,authentication,content,links,compliance,audience,routing"`
	Title   string `json:"title"`
	Status  string `json:"status" enum:"queued,running,pass,warn,block,unknown"`
	Text    string `json:"text"`
	Done    int    `json:"done"`
	Total   int    `json:"total"`
	Checked int    `json:"checked"`
}

ReadinessProgressGroup is one group of a run in progress.

type ReadinessProgressView

type ReadinessProgressView struct {
	Running *ReadinessProgress `json:"running,omitempty"`
}

ReadinessProgressView is the run in progress, if any.

type ReadinessResult

type ReadinessResult struct {
	Verdict string           `json:"verdict" enum:"ready,warnings,blocked"`
	Counts  ReadinessCounts  `json:"counts"`
	Groups  []ReadinessGroup `json:"groups"`
	Checks  []ReadinessCheck `json:"checks"`
	// Incomplete is true when some checks couldn't run (Unknown); the
	// verdict then can't be Ready until a person continues without them.
	Incomplete bool `json:"incomplete"`
	// Problem says why checks are unknown ("api.hostrepute.com timed out…").
	Problem   string             `json:"problem,omitempty"`
	Estimates ReadinessEstimates `json:"estimates"`
}

ReadinessResult is what Assemble produces and a run stores.

func Assemble

func Assemble(f Facts) ReadinessResult

Assemble builds the checklist and the estimates from what a run gathered.

type ReadinessRoute

type ReadinessRoute struct {
	Stream string `json:"stream" enum:"broadcast,automation,system"`
	// StreamLabel is "Broadcasts"; SplitLabel "Broadcasts 90 / 10".
	StreamLabel string                `json:"streamLabel"`
	SplitLabel  string                `json:"splitLabel"`
	Policy      string                `json:"policy" enum:"automatic,pause_and_ask,warm_only"`
	Override    bool                  `json:"override"`
	Shares      []ReadinessRouteShare `json:"shares"`
	TotalCost   float64               `json:"totalCost"`
	// TotalMinutes is the longest route (routes run in parallel) or the
	// slowest mailbox provider throttle, whichever is longer.
	TotalMinutes int                `json:"totalMinutes"`
	Down         int                `json:"down"`
	Move         *ReadinessHeldMove `json:"move,omitempty"`
}

ReadinessRoute is the route breakdown with cost and duration estimates.

type ReadinessRouteShare

type ReadinessRouteShare struct {
	ProviderID string  `json:"providerId"`
	Name       string  `json:"name"`
	Short      string  `json:"short"`
	Adapter    string  `json:"adapter"`
	Label      string  `json:"label,omitempty"`
	Color      string  `json:"color" enum:"ses,postal,postmark,other"`
	Percent    float64 `json:"percent"`
	Recipients int64   `json:"recipients"`
	Status     string  `json:"status"`
	// StatusLabel is "Healthy", "Warming up · day 9 of 21", "Down since 08:52".
	StatusLabel string `json:"statusLabel"`
	WarmupDay   int    `json:"warmupDay,omitempty"`
	WarmupDays  int    `json:"warmupDays,omitempty"`
	// Available is false when the provider can't take mail (down, paused,
	// webhooks silent); its share is held.
	Available bool `json:"available"`
	// Cost in US dollars; PriceLabel is "$0.10 per 1,000" or "self-hosted".
	Cost       float64 `json:"cost"`
	PriceLabel string  `json:"priceLabel"`
	// Rate is messages per second; RateLabel "14 /s" or "2 /s ramp".
	Rate      float64 `json:"rate"`
	RateLabel string  `json:"rateLabel"`
	Minutes   int     `json:"minutes"`
}

ReadinessRouteShare is one sending provider's part of the send.

type ReadinessRun

type ReadinessRun struct {
	ID         string    `json:"id"`
	CampaignID string    `json:"campaignId"`
	Trigger    string    `json:"trigger" enum:"manual,composer,schedule,send_time,approval"`
	RanAt      time.Time `json:"ranAt"`
	RanBy      string    `json:"ranBy,omitempty"`
	DurationMs int       `json:"durationMs"`
	// Version is the campaign version the run checked.
	Version int `json:"version"`
	ReadinessResult
	// UnknownAccepted is set when someone chose to continue with provider
	// data only.
	UnknownAcceptedAt *time.Time `json:"unknownAcceptedAt,omitempty"`
	UnknownAcceptedBy string     `json:"unknownAcceptedBy,omitempty"`
	// Fingerprint is what the run checked; it changes with the content,
	// audience, route or schedule.
	Fingerprint string `json:"-"`
}

ReadinessRun is a stored run.

type ReadinessSchedule

type ReadinessSchedule struct {
	Mode string `json:"mode" enum:"now,at,best_time"`
	// Date and Time are local to Timezone ("2026-10-14", "09:00").
	Date     string `json:"date,omitempty" pattern:"^\\d{4}-\\d{2}-\\d{2}$"`
	Time     string `json:"time,omitempty" pattern:"^([01]\\d|2[0-3]):[0-5]\\d$"`
	Timezone string `json:"timezone,omitempty" maxLength:"64"`
	// At is the resulting instant (read-only).
	At *time.Time `json:"at,omitempty" readOnly:"true"`
}

ReadinessSchedule is when the campaign goes out: now, at a local date and time in a time zone, or at each recipient's usual open time within 24 h of that time.

func ScheduleView

func ScheduleView(raw json.RawMessage, wsTZ string) ReadinessSchedule

ScheduleView turns the stored schedule into the API shape, in the workspace's zone when the schedule has none.

func (ReadinessSchedule) Resolve

func (in ReadinessSchedule) Resolve(field string) (Schedule, *time.Time, error)

Resolve validates the schedule and returns its stored shape.

type ReadinessSendSettings

type ReadinessSendSettings struct {
	Thresholds *ReadinessThresholds `json:"thresholds,omitempty"`
	Schedule   *ReadinessSchedule   `json:"schedule,omitempty"`
}

ReadinessSendSettings are the editable settings of Review & send.

type ReadinessThresholds

type ReadinessThresholds struct {
	// Bounce rate in percent.
	Bounce float64 `json:"bounce" minimum:"0.1" maximum:"20"`
	// Complaint rate in percent, overall and per mailbox provider.
	Complaint        float64 `json:"complaint" minimum:"0.01" maximum:"5"`
	MailboxComplaint float64 `json:"mailboxComplaint" minimum:"0.01" maximum:"5"`
	// ProviderErrors is the share of failed API calls over 3 minutes, in percent.
	ProviderErrors float64 `json:"providerErrors" minimum:"1" maximum:"100"`
	// Scope: pause only the affected route or mailbox provider, or the whole campaign.
	Scope string `json:"scope" enum:"route,campaign"`
}

ReadinessThresholds are the auto-pause thresholds of a send. The sending engine enforces them; they're stored on campaigns.thresholds as {"bounce":2.0,"complaint":0.10,"mailbox_complaint":0.10,"provider_errors":5,"scope":"route"}.

func ParseThresholds

func ParseThresholds(campaign, workspace json.RawMessage) ReadinessThresholds

ParseThresholds reads a campaign's thresholds, falling back to the workspace's defaults (send_thresholds) and then to 2% / 0.10% / 0.10% / 5%.

type ReadinessThrottle

type ReadinessThrottle struct {
	Key        string `json:"key" enum:"gmail,outlook,yahoo,icloud,other"`
	Name       string `json:"name"`
	Recipients int64  `json:"recipients"`
	// Rate is messages per second; 0 means the provider's full rate.
	Rate float64 `json:"rate"`
}

ReadinessThrottle is the rate for one mailbox provider.

type Recipient

type Recipient struct {
	Email           string
	MailboxProvider string
	Lists           []string
	Tier            string
}

Recipient is one final recipient, as routing needs it.

type ReputationFacts

type ReputationFacts struct {
	// Status is pass, warn, block or unknown (deliverability's verdict).
	Status string
	// Via is hostrepute, builtin or none; Sources is how many lists.
	Via     string
	Sources int
	// Reason explains an unknown status; Outage is HostRepute's error
	// ("Couldn't reach api.hostrepute.com (timeout after 30 s, 3 attempts)").
	Reason    string
	Outage    string
	CheckedAt *time.Time
	// DomainSources and IPSources name the lists that check domains and IPs,
	// most important first.
	DomainSources []string
	IPSources     []string
	// Listings of the campaign's assets.
	Listings []ListingFacts
}

ReputationFacts are the blocklist results (HostRepute or the built-in checks).

type RouteConfig

type RouteConfig struct {
	Key         string
	Label       string
	StreamLabel string
}

RouteConfig describes the routing a campaign uses: its override, or the Broadcasts default split. Key changes when the split changes; Label is "SES 90 / Postal 10" and StreamLabel "Broadcasts 90 / 10".

type RouteFacts

type RouteFacts struct {
	Stream string
	// Policy is the stream's failover policy.
	Policy   string
	Override bool
	// NoRoute is true when the stream has no provider.
	NoRoute bool
	Shares  []ShareFacts
}

RouteFacts is the sending route of the campaign and its providers.

type RouteOverride

type RouteOverride struct {
	Splits []routing.Split `json:"splits"`
}

RouteOverride is campaigns.route_override: a split that replaces the stream's rules for this campaign ("Send via SES only").

func ParseRouteOverride

func ParseRouteOverride(raw json.RawMessage) *RouteOverride

ParseRouteOverride reads campaigns.route_override (nil when unset).

type RunOptions

type RunOptions struct {
	Trigger string
	// By is the person who asked (nil for jobs).
	By *uuid.UUID
}

RunOptions describe a run.

type Schedule

type Schedule struct {
	Mode     string `json:"mode"`
	At       string `json:"at,omitempty"`
	Timezone string `json:"timezone,omitempty"`
}

Schedule is campaigns.schedule.

func ParseSchedule

func ParseSchedule(raw json.RawMessage) Schedule

ParseSchedule reads campaigns.schedule (mode "now" when unset).

func (Schedule) StartAt

func (s Schedule) StartAt(now time.Time) time.Time

StartAt is when a send with this schedule would start.

type SegmentResolver

type SegmentResolver interface {
	ContactIDs(ctx context.Context, workspaceID, segmentID uuid.UUID) ([]uuid.UUID, error)
}

SegmentResolver lists a segment's contacts (the audience domain's segments.Service). Without one, segments in an audience aren't counted.

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Log   *slog.Logger
	Now   func() time.Time
	// Campaigns runs the composer's content and link checks and saves the
	// content changes fixes make.
	Campaigns *campaigns.Service
	// Deliverability reads blocklists, authentication and provider health.
	Deliverability Deliverability
	// Segments resolves segment members; nil until the audience domain wires it.
	Segments SegmentResolver
	// URLs builds the one-click unsubscribe link.
	URLs publicurl.Builder
	// AfterChange is told when a fix or a send setting changed a campaign.
	AfterChange AfterChange
}

Service runs Send Readiness and applies its fixes.

func (*Service) AcceptUnknown

func (s *Service) AcceptUnknown(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID, runID uuid.UUID) (ReadinessRun, error)

AcceptUnknown records "Continue with provider data only" on the latest run.

func (*Service) ApplyFixes

ApplyFixes applies one-click fixes to a campaign. Content fixes save a new version through the composer; audience and route fixes change the campaign. Each change is audited.

func (*Service) Audience

func (s *Service) Audience(ctx context.Context, ws *store.Workspace, raw json.RawMessage) (AudienceFacts, error)

Audience counts the final recipients of a stored audience definition.

func (*Service) Campaign

Campaign loads a campaign as a run sees it.

func (*Service) ClearRouteOverride

func (s *Service) ClearRouteOverride(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) error

ClearRouteOverride puts the campaign back on the stream's routing.

func (*Service) CurrentFingerprint

func (s *Service) CurrentFingerprint(ctx context.Context, ws *store.Workspace, c store.ReadinessCampaignRow) string

CurrentFingerprint is the fingerprint of the campaign as it stands.

func (*Service) Get

func (s *Service) Get(ctx context.Context, campaignID, runID uuid.UUID) (*ReadinessRun, error)

Get returns one run of a campaign.

func (*Service) Latest

func (s *Service) Latest(ctx context.Context, campaignID uuid.UUID) (*ReadinessRun, error)

Latest returns the latest run of a campaign, nil when it never ran.

func (*Service) Progress

func (s *Service) Progress(ctx context.Context, campaignID uuid.UUID) (*ReadinessProgress, error)

Progress returns the run in progress, nil when none is.

func (*Service) Route

func (s *Service) Route(ctx context.Context, ws *store.Workspace, override json.RawMessage) (RouteConfig, error)

Route returns the routing configuration of a campaign.

func (*Service) Run

Run runs every check on a campaign and stores the result. It returns ErrRunning when a run is already in progress.

func (*Service) UpdateSendSettings

func (s *Service) UpdateSendSettings(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID, in ReadinessSendSettings) error

UpdateSendSettings saves the thresholds and the schedule the person chose. Changing the schedule after approval invalidates the approval.

type ShareFacts

type ShareFacts struct {
	ProviderID string
	Name       string
	Short      string
	Adapter    string
	Label      string
	Recipients int64
	// Percent of the final audience.
	Percent float64
	// Status is the provider status (healthy, warming_up, down…).
	Status    string
	Available bool
	// DownSince and DownDetail describe an outage ("mta.acme.io has refused
	// connections since 08:52 (ECONNREFUSED on port 25 and 443)").
	DownSince  *time.Time
	DownDetail string
	// Warm-up: day and length of the plan, the cap on the send day and
	// whether that day is today.
	WarmupDay   int
	WarmupDays  int
	WarmupCap   int64
	WarmupToday bool
	// Rate is the provider's send rate (messages per second); RateRamp is
	// true when it comes from a warm-up plan.
	Rate     float64
	RateRamp bool
	Pricing  state.Pricing
	// Bounce and Complaint are 7-day rates in percent (nil without volume);
	// ProviderReported is true when the provider measured them.
	Bounce           *float64
	Complaint        *float64
	ProviderReported bool
	Limits           state.Limits
	// Account is the account standing ("Production · no enforcement").
	Account string
	Sandbox bool
	Quota   *state.Quota
	// BulkAllowed says whether the provider's terms allow bulk marketing;
	// Terms explains it ("yes, with production access").
	BulkAllowed bool
	Terms       string
	Tracking    state.Tracking
	// IPs are the provider's dedicated IPs (empty for shared pools).
	IPs         []string
	ConnectedAt time.Time
}

ShareFacts is one provider of the route with what the checks need.

Jump to

Keyboard shortcuts

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