placement

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: 46 Imported by: 0

Documentation

Overview

Package placement runs placement tests: one copy of an email to each seed mailbox the workspace owns, through the route as configured, one provider or several side by side, then finds each copy by its test token and says where it landed (Inbox, a tab, Spam, Not arrived), how long it took, and what the mailbox's Authentication-Results say.

Tests are one-off checks people start (Review & send, the composer, the warm-up planner, Placement tests): no schedules and no alerts, which are HostRepute's side of the line. A test never changes or blocks a send. Copies are real sends with the same headers and link tracking; their opens and clicks are never counted and they never appear in reports or contact timelines.

Index

Constants

View Source
const (
	ReasonSignInFailed  = "signin_failed"
	ReasonSignInExpired = "signin_expired"
	ReasonSeedRemoved   = "seed_removed"
	ReasonStopped       = "stopped"
	ReasonUnsent        = "unsent"
)

Why a copy wasn't looked for (placement_copies.not_checked).

View Source
const (
	WaitFor    = 15 * time.Minute
	LateWithin = 60 * time.Minute
	// CompareGap separates the two providers' copies to a seed.
	CompareGap = 2 * time.Minute
)

Waiting: a copy missing 15 minutes after the last hand-off is Not arrived; one that turns up within 60 minutes updates the result.

View Source
const CallbackPath = "/api/v1/placement/oauth/callback"

CallbackPath is where Google and Microsoft send the browser back after a seed's consent. It's fixed per instance, so one redirect URI is added to each sign-in app; the state names the workspace.

View Source
const Kind = "placement"

Kind is the messages.kind of a copy.

Variables

View Source
var (

	// MFinishedTitle and the rest word the notifications (internal/app).
	MFinishedTitle   = msgs.M("notify.finishedTitle")
	MSeedFailedTitle = msgs.M("notify.seedFailedTitle")
	MSeedFailedBody  = msgs.M("notify.seedFailedBody")
	MSeedExpiredBody = msgs.M("notify.seedExpiredBody")
)
View Source
var GoogleScopes = []string{"https://mail.google.com/", "openid", "email"}

GoogleScopes are what a Gmail or Google Workspace seed is connected with: IMAP with XOAUTH2 needs https://mail.google.com/ (Google's restricted scope; see docs/integrations/seed-mailboxes.md).

Functions

func DemoAuth

func DemoAuth(raw string) json.RawMessage

DemoAuth is a demo copy's parsed authentication results (the seeder stores it with the copy).

func DemoFolders

func DemoFolders(provider, auth string) []seedbox.Folder

DemoFolders are the folders a seed of provider shows (the seeder uses them too).

func DemoHeaders

func DemoHeaders(m DemoMail) string

DemoHeaders writes the headers a mailbox provider would show for a demo copy: its Authentication-Results (all passing), the Received line of the hand-over, the Message-ID and the test token.

func DemoHop

func DemoHop(raw string) json.RawMessage

DemoHop is a demo copy's hand-over hop.

func Helpers

func Helpers(ctx context.Context, q *store.Queries, wsID uuid.UUID, perm authz.Permission) []string

Helpers names up to three active members who hold perm, narrowest role first and the Owner last ("Ask Sofia Rossi, Marcus Chen or Linh Nguyen").

func NameIn

func NameIn(l i18n.Lang, name, content string) string

NameIn is a test's name for a reader: its content's name, then the providers it went through, compared in the reader's words ("Weekly Digest #142 · SES so với Postal"). The stored name keeps its English.

func Register

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

Register adds the placement test operations.

func RegisterJobs

func RegisterJobs(reg *jobs.Registry, s *Service)

RegisterJobs adds the workers and the periodic jobs.

func SealCredentials

func SealCredentials(s interface {
	Seal([]byte, string) ([]byte, error)
}, seedID uuid.UUID, password string, demo bool) ([]byte, error)

SealCredentials seals a seed's password or tokens (the demo seeds with it).

Types

type CheckArgs

type CheckArgs struct{}

CheckArgs looks for the copies of every test that is sending or waiting, and for late copies of tests that finished within the hour.

func (CheckArgs) Kind

func (CheckArgs) Kind() string

Kind implements river.JobArgs.

type CheckWorker

type CheckWorker struct {
	river.WorkerDefaults[CheckArgs]
	Svc *Service
}

CheckWorker runs CheckArgs.

func (*CheckWorker) Timeout

func (w *CheckWorker) Timeout(*river.Job[CheckArgs]) time.Duration

Timeout leaves room for slow mailboxes (each sign-in has its own timeout).

func (*CheckWorker) Work

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

Work implements river.Worker.

type ConditionalVersion

type ConditionalVersion struct {
	Number     int
	Shows      string
	Recipients int64
	Hidden     string
}

ConditionalVersion is a version of an email with conditional content: what it shows, how many recipients get it and the blocks it leaves out (as messages.hidden_blocks stores them).

type DeleteArgs

type DeleteArgs struct{}

DeleteArgs deletes the copies that are due to go from the seeds.

func (DeleteArgs) Kind

func (DeleteArgs) Kind() string

Kind implements river.JobArgs.

type DeleteWorker

type DeleteWorker struct {
	river.WorkerDefaults[DeleteArgs]
	Svc *Service
}

DeleteWorker runs DeleteArgs.

func (*DeleteWorker) Timeout

func (w *DeleteWorker) Timeout(*river.Job[DeleteArgs]) time.Duration

Timeout leaves room for slow mailboxes.

func (*DeleteWorker) Work

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

Work implements river.Worker.

type DemoMail

type DemoMail struct {
	SeedProvider string
	// Host and IP are the sending server's.
	Host, IP string
	From     string
	// MessageID is the Message-ID's left part (the copy's id by default).
	MessageID string
	Token     string
	// Selector and SPFDomain are the DKIM selector and the Return-Path
	// domain ("7kq2n3x", "bounce.news.acme.io").
	Selector, SPFDomain string
	At                  time.Time
}

DemoMail describes a demo copy for its headers.

type DemoOutcome

type DemoOutcome struct {
	Role, Folder, Tab string
	After             time.Duration
}

DemoOutcome is where a demo copy lands and how long it takes.

func DemoLanding

func DemoLanding(seedProvider, stream string, warming bool, token string) DemoOutcome

DemoLanding picks a demo copy's folder: Gmail sorts newsletters into Promotions, Microsoft into Focused or Other, a warming-up IP lands in Outlook's and Yahoo's spam, and transactional mail goes to the inbox.

type Digests

type Digests interface {
	NextIssueCampaign(ctx context.Context, ws *store.Workspace, p *authz.Principal, digestID uuid.UUID, fresh bool) (uuid.UUID, error)
}

Digests gives the campaign of a recurring digest's next issue (internal/digests): the one already built for checks, or a fresh build.

type Endpoints

type Endpoints struct {
	GoogleAuth, GoogleToken string
	// MicrosoftBase is the identity platform ("https://login.microsoftonline.com").
	MicrosoftBase string
}

Endpoints are the OAuth endpoints of the two sign-in apps.

type MailApp

type MailApp struct {
	Kind         string
	ClientID     string
	ClientSecret string
	// Tenant is Microsoft's (common, organizations, consumers or one tenant).
	Tenant string
}

MailApp is the instance's Google or Microsoft sign-in app (Instance admin › Authentication) as seed mailboxes use it for mail access.

type MailApps

type MailApps interface {
	MailApp(ctx context.Context, kind string) (MailApp, bool, error)
}

MailApps reads the instance's sign-in apps.

type Notifier

type Notifier interface {
	TestFinished(ctx context.Context, ws *store.Workspace, t store.PlacementTest, summary string)
	SeedFailed(ctx context.Context, ws *store.Workspace, seed store.PlacementSeed)
}

Notifier tells the starter a test finished and managers a seed failed.

type PlacementAuthCheck

type PlacementAuthCheck struct {
	Result   string `json:"result"`
	Domain   string `json:"domain,omitempty"`
	Selector string `json:"selector,omitempty"`
	IP       string `json:"ip,omitempty"`
	Aligned  *bool  `json:"aligned,omitempty"`
	Detail   string `json:"detail,omitempty"`
}

PlacementAuthCheck is one authentication result of a copy, in full.

type PlacementAuthCount

type PlacementAuthCount struct {
	Pass int `json:"pass"`
	Fail int `json:"fail"`
}

PlacementAuthCount is one check across copies.

type PlacementAuthReadiness

type PlacementAuthReadiness struct {
	Passed   int      `json:"passed"`
	Warnings int      `json:"warnings"`
	Blocks   int      `json:"blocks"`
	Blocking []string `json:"blocking" doc:"The blocking checks, in the reader's language"`
	Evidence []string `json:"evidence" doc:"One sentence per blocking check"`
}

PlacementAuthReadiness is Send Readiness's latest verdict on the campaign.

type PlacementAuthSummary

type PlacementAuthSummary struct {
	// Checked copies carried Authentication-Results.
	Checked int                `json:"checked"`
	SPF     PlacementAuthCount `json:"spf"`
	DKIM    PlacementAuthCount `json:"dkim"`
	DMARC   PlacementAuthCount `json:"dmarc"`
	// The signing domain and selector, and the SPF domain, most copies showed.
	DKIMDomain   string `json:"dkimDomain,omitempty"`
	DKIMSelector string `json:"dkimSelector,omitempty"`
	SPFDomain    string `json:"spfDomain,omitempty"`
}

PlacementAuthSummary is SPF, DKIM and DMARC across a provider's copies, from the mailboxes' own Authentication-Results.

func (PlacementAuthSummary) AllPass

func (a PlacementAuthSummary) AllPass() bool

AllPass reports whether every checked copy passed all three.

type PlacementConditionalVersion

type PlacementConditionalVersion struct {
	Number int `json:"number"`
	// Shows names its conditional blocks ("Beta corner, Start a free
	// trial"), "" for none of them.
	Shows      string `json:"shows"`
	Recipients int64  `json:"recipients"`
}

PlacementConditionalVersion is a version of an email with conditional content: who gets which blocks.

type PlacementContentList

type PlacementContentList struct {
	Items []PlacementContentOption `json:"items"`
}

PlacementContentList is the dialog's content search.

type PlacementContentOption

type PlacementContentOption struct {
	Kind string    `json:"kind" enum:"campaign,template,digest,transactional"`
	ID   string    `json:"id"`
	Name string    `json:"name"`
	Note string    `json:"note" doc:"A campaign's status, template, a transactional template's key, or a digest's state (on, paused, off)"`
	At   time.Time `json:"at"`
}

PlacementContentOption is something a test can send.

type PlacementContentRef

type PlacementContentRef struct {
	Kind string `json:"kind" enum:"campaign,template,digest,transactional"`
	ID   string `json:"id" doc:"A campaign, template, recurring digest (its next issue) or transactional template id"`
}

PlacementContentRef names what a test sends.

type PlacementContentView

type PlacementContentView struct {
	Kind        string     `json:"kind" enum:"campaign,template,digest,transactional"`
	ID          string     `json:"id"`
	Name        string     `json:"name"`
	Status      string     `json:"status,omitempty"`
	Version     int        `json:"version,omitempty"`
	Key         string     `json:"key,omitempty"`
	Category    string     `json:"category,omitempty"`
	ScheduledAt *time.Time `json:"scheduledAt,omitempty"`
	SentAt      *time.Time `json:"sentAt,omitempty"`
	Audience    string     `json:"audience,omitempty"`
	Recipients  *int64     `json:"recipients,omitempty"`
	// Variants, languages and test data sets the email has.
	Variants  []PlacementVariant  `json:"variants"`
	Languages []PlacementLanguage `json:"languages"`
	TestData  []string            `json:"testData"`
	// Sensitive variables carry a placeholder in copies (reset_url);
	// TestValues are the chosen set's other values (first_name "Sam").
	Sensitive  []string             `json:"sensitive"`
	TestValues []PlacementTestValue `json:"testValues"`
	// FallbackGreeting is the fallbacks' greeting ("Hi there").
	FallbackGreeting string `json:"fallbackGreeting,omitempty"`
	// Conditional are the email's conditional-content versions (X11),
	// ConditionalVersion the one the test sends.
	Conditional        []PlacementConditionalVersion `json:"conditional"`
	ConditionalVersion int                           `json:"conditionalVersion,omitempty"`
}

PlacementContentView is the email the dialog shows under Content.

type PlacementCopyCost

type PlacementCopyCost struct {
	ProviderID string  `json:"providerId"`
	Short      string  `json:"short"`
	Copies     int     `json:"copies"`
	Cost       float64 `json:"cost"`
	// Pricing and a plan's monthly allowance ("Inside Postmark's plan of 10,000 a month").
	Pricing     string `json:"pricing" enum:"metered,plan,self_hosted"`
	PlanMonthly int64  `json:"planMonthly,omitempty"`
	// Warm-up: today's cap and what's sent, when the provider warms up.
	WarmDay   int   `json:"warmDay,omitempty"`
	TodayCap  int64 `json:"todayCap,omitempty"`
	SentToday int64 `json:"sentToday,omitempty"`
}

PlacementCopyCost is a provider's copies and their cost.

type PlacementCopyDetail

type PlacementCopyDetail struct {
	Copy PlacementCopyView `json:"copy"`
	// Path is the folder as the mailbox reports it ("acme.seed@outlook.com › Junk Email").
	Path string `json:"path,omitempty"`
	// ReadVia is how the seed was read.
	ReadVia string              `json:"readVia" enum:"imap,graph,gmail"`
	SPF     *PlacementAuthCheck `json:"spf,omitempty"`
	DKIM    *PlacementAuthCheck `json:"dkim,omitempty"`
	DMARC   *PlacementAuthCheck `json:"dmarc,omitempty"`
	// KeyHeaders are the lines that matter (Authentication-Results, the
	// hand-over Received, Message-ID and X-ReputeCast-Test); Headers all of them.
	KeyHeaders string           `json:"keyHeaders"`
	Headers    string           `json:"headers"`
	Events     []PlacementEvent `json:"events"`
	// ProviderMessageID is the provider's own id for the copy.
	ProviderMessageID string     `json:"providerMessageId,omitempty"`
	WaitUntil         *time.Time `json:"waitUntil,omitempty"`
	TestStatus        string     `json:"testStatus"`
}

PlacementCopyDetail is a copy's detail: where it landed, its authentication and headers, and the provider's events.

type PlacementCopyView

type PlacementCopyView struct {
	ID               string `json:"id"`
	SeedID           string `json:"seedId,omitempty"`
	SeedEmail        string `json:"seedEmail"`
	SeedProvider     string `json:"seedProvider"`
	SeedProviderName string `json:"seedProviderName"`
	ProviderID       string `json:"providerId,omitempty"`
	ProviderName     string `json:"providerName"`
	Round            int    `json:"round"`
	// First is set in a comparison when this provider's copy went first.
	First      bool       `json:"first"`
	Status     string     `json:"status" enum:"queued,sent,failed,found,not_arrived,not_checked"`
	Folder     string     `json:"folder,omitempty" enum:"inbox,tab,spam,"`
	FolderName string     `json:"folderName,omitempty" doc:"The mailbox's own name: Junk Email, Bulk, Spamverdacht"`
	Tab        string     `json:"tab,omitempty" doc:"Primary, Promotions, Focused, Other"`
	Late       bool       `json:"late"`
	SendAt     time.Time  `json:"sendAt"`
	HandedAt   *time.Time `json:"handedAt,omitempty"`
	ReceivedAt *time.Time `json:"receivedAt,omitempty"`
	ArriveMs   *int64     `json:"arriveMs,omitempty"`
	SPF        string     `json:"spf,omitempty"`
	DKIM       string     `json:"dkim,omitempty"`
	DMARC      string     `json:"dmarc,omitempty"`
	// Reason says why it wasn't looked for; ReasonAt is when the seed's
	// sign-in failed, or when the test stopped.
	Reason   string     `json:"reason,omitempty" enum:"signin_failed,signin_expired,seed_removed,stopped,unsent,"`
	ReasonAt *time.Time `json:"reasonAt,omitempty"`
	// Deferrals and the provider's latest event while it isn't found.
	Deferrals int             `json:"deferrals"`
	LastEvent *PlacementEvent `json:"lastEvent,omitempty"`
	Error     string          `json:"error,omitempty" doc:"Why the provider refused the copy"`
	// LateUntil is how long ReputeCast keeps looking for it.
	LateUntil *time.Time `json:"lateUntil,omitempty"`
}

PlacementCopyView is one copy: a cell of the matrix.

type PlacementCounts

type PlacementCounts struct {
	// Copies went out or are about to; Found were found in a seed.
	Copies     int `json:"copies"`
	Found      int `json:"found"`
	Inbox      int `json:"inbox"`
	Tab        int `json:"tab"`
	Spam       int `json:"spam"`
	NotArrived int `json:"notArrived"`
	NotChecked int `json:"notChecked"`
	// Waiting were sent (or are queued) and aren't found yet; Failed the
	// provider refused; Unsent never went because the test was stopped.
	Waiting int `json:"waiting"`
	Failed  int `json:"failed"`
	Unsent  int `json:"unsent"`
	// Tabs are the inbox tabs copies landed in ("Promotions").
	Tabs            []string              `json:"tabs"`
	NotCheckedSeeds []PlacementNotChecked `json:"notCheckedSeeds"`
}

PlacementCounts are copies by where they landed.

type PlacementEarlier

type PlacementEarlier struct {
	TestID      string    `json:"testId"`
	ContentName string    `json:"contentName"`
	Inbox       int       `json:"inbox"`
	Copies      int       `json:"copies"`
	StartedAt   time.Time `json:"startedAt"`
}

PlacementEarlier is an earlier test through the same provider.

type PlacementEvent

type PlacementEvent struct {
	Type       string    `json:"type" doc:"delivered, deferred, soft_bounce, hard_bounce, complaint, rejected…"`
	At         time.Time `json:"at"`
	Code       string    `json:"code,omitempty"`
	Diagnostic string    `json:"diagnostic,omitempty"`
	// Host is the receiving server the provider named ("mx-ha03.web.de").
	Host string `json:"host,omitempty"`
}

PlacementEvent is a provider's event for a copy.

type PlacementFacet

type PlacementFacet struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

PlacementFacet is a filter choice of the list.

type PlacementFolder

type PlacementFolder struct {
	Role  string `json:"role" enum:"inbox,tab,spam"`
	Name  string `json:"name"`
	Label string `json:"label"`
}

PlacementFolder is a folder found in a seed.

type PlacementGuidance

type PlacementGuidance struct {
	ProviderID   string `json:"providerId"`
	ProviderName string `json:"providerName"`
	Spam         int    `json:"spam"`
	Copies       int    `json:"copies"`
	// At names the mailbox providers where copies went to spam, when few.
	At []string `json:"at"`
	// Cause picks the explanation: Send Readiness blocks the email, the
	// authentication failed, a warming-up IP, or the sender's reputation.
	Cause string `json:"cause" enum:"readiness,auth,warmup,reputation"`
	// Auth is across every provider of the test; AuthProviders how many.
	Auth          PlacementAuthSummary    `json:"auth"`
	AuthProviders int                     `json:"authProviders"`
	Readiness     *PlacementAuthReadiness `json:"readiness,omitempty"`
	Other         *PlacementOther         `json:"other,omitempty"`
	Earlier       *PlacementEarlier       `json:"earlier,omitempty"`
	// The provider then: status, warm-up day and IP.
	Status     string `json:"status"`
	WarmDay    int    `json:"warmDay,omitempty"`
	WarmDays   int    `json:"warmDays,omitempty"`
	IP         string `json:"ip,omitempty"`
	HostRepute bool   `json:"hostRepute"`
}

PlacementGuidance explains a provider's spam results with ReputeCast's own rules (never AI): the likeliest cause and what to look at.

type PlacementLanguage

type PlacementLanguage struct {
	Code   string `json:"code"`
	Source bool   `json:"source"`
}

PlacementLanguage is a language version of the email.

type PlacementMailboxResult

type PlacementMailboxResult struct {
	Provider string `json:"provider" doc:"The seed mailbox provider's key (gmail)"`
	Name     string `json:"name" doc:"Gmail, Outlook.com, Yahoo"`
	// Tab is the inbox tab the provider sorts bulk mail into ("Promotions"
	// at Gmail, "Other" at Outlook.com), empty for providers without tabs.
	Tab    string          `json:"tab,omitempty"`
	Counts PlacementCounts `json:"counts"`
}

PlacementMailboxResult is where a test's copies landed at one mailbox provider (Gmail, Outlook.com, Yahoo…), whichever sending provider carried them: Review & send's placement card shows Inbox, Promotions and Spam per mailbox provider (SR-9).

type PlacementNotChecked

type PlacementNotChecked struct {
	Provider string `json:"provider"`
	Name     string `json:"name" doc:"The seed's mailbox provider (iCloud)"`
	Email    string `json:"email"`
	Reason   string `json:"reason" enum:"signin_failed,signin_expired,seed_removed,stopped,unsent"`
}

PlacementNotChecked is a seed whose copy couldn't be looked for.

type PlacementOAuthInput

type PlacementOAuthInput struct {
	Provider string `json:"provider" enum:"gmail,google_workspace,outlook,microsoft_365"`
	// SeedID reconnects an existing seed.
	SeedID string `json:"seedId,omitempty"`
	// Email is the seed's address, as a hint for the account picker.
	Email string `json:"email,omitempty" maxLength:"254"`
}

PlacementOAuthInput starts a seed's OAuth consent.

type PlacementOAuthStart

type PlacementOAuthStart struct {
	URL string `json:"url"`
}

PlacementOAuthStart is where to send the browser.

type PlacementOther

type PlacementOther struct {
	ProviderID string `json:"providerId"`
	Name       string `json:"name"`
	Inbox      int    `json:"inbox"`
	Spam       int    `json:"spam"`
	Copies     int    `json:"copies"`
}

PlacementOther is the same email through another provider in the test.

type PlacementPlan

type PlacementPlan struct {
	Content   PlacementContentView      `json:"content"`
	Stream    string                    `json:"stream" enum:"broadcast,automation,system,transactional"`
	Providers []PlacementProviderOption `json:"providers"`
	// Chosen are the providers the test would use (route: those the route picks).
	Chosen  []string                `json:"chosen"`
	Route   []PlacementRouteShare   `json:"route"`
	Senders []PlacementSenderOption `json:"senders"`
	Sender  string                  `json:"sender,omitempty"`
	// SenderProblem: no sender of the stream is verified on the chosen
	// providers; SenderMissing names the ones without one, and
	// SenderAlternatives the other providers that have one.
	SenderProblem      string                `json:"senderProblem,omitempty"`
	SenderDomain       string                `json:"senderDomain,omitempty"`
	SenderMissing      []string              `json:"senderMissing,omitempty"`
	SenderAlternatives []string              `json:"senderAlternatives,omitempty"`
	Seeds              []PlacementSeedChoice `json:"seeds"`
	Copies             int                   `json:"copies"`
	Costs              []PlacementCopyCost   `json:"costs"`
	// Problems keep the test from starting; CompareProblem explains a
	// comparison with fewer than two usable providers.
	Problems       []string `json:"problems"`
	CompareProblem string   `json:"compareProblem,omitempty"`
	// Alone is the one provider a comparison can still test.
	Alone    string `json:"alone,omitempty"`
	CanStart bool   `json:"canStart"`
	CanRun   bool   `json:"canRun"`
	// RunHelpers hold placement:run.
	RunHelpers []string `json:"runHelpers"`
	// Earlier tests through a warming-up provider ("day 2, day 5 and day 9").
	WarmupDays []int `json:"warmupDays"`
}

PlacementPlan is what a test would send, for the dialog.

type PlacementProviderOption

type PlacementProviderOption struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Short    string `json:"short"`
	Adapter  string `json:"adapter"`
	Color    string `json:"color"`
	Detail   string `json:"detail" doc:"us-east-1, mta.acme.io, the Transactional stream"`
	Status   string `json:"status" enum:"healthy,degraded,down,sandbox,warming_up,paused"`
	WarmDay  int    `json:"warmDay,omitempty"`
	WarmDays int    `json:"warmDays,omitempty"`
	// DownSince and DownReason explain an outage.
	DownSince  *time.Time `json:"downSince,omitempty"`
	DownReason string     `json:"downReason,omitempty"`
	// StreamOnly: the provider carries only another stream (Postmark's
	// Transactional stream) and can't send this email.
	StreamOnly string `json:"streamOnly,omitempty"`
	Available  bool   `json:"available"`
	// CostPerCopy in dollars (metered pricing; 0 for plans and self-hosted).
	CostPerCopy float64 `json:"costPerCopy"`
	// Pricing is the provider's model; PlanMonthly a plan's monthly allowance.
	Pricing     string `json:"pricing" enum:"metered,plan,self_hosted"`
	PlanMonthly int64  `json:"planMonthly,omitempty"`
	// TodayCap and SentToday: a warming-up provider's allowance.
	TodayCap  int64 `json:"todayCap,omitempty"`
	SentToday int64 `json:"sentToday,omitempty"`
}

PlacementProviderOption is a provider the dialog offers.

type PlacementProviderResult

type PlacementProviderResult struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Short   string `json:"short"`
	Adapter string `json:"adapter"`
	Color   string `json:"color"`
	Detail  string `json:"detail"`
	IP      string `json:"ip,omitempty"`
	// Status and warm-up day as they were when the test started.
	Status   string               `json:"status"`
	WarmDay  int                  `json:"warmDay,omitempty"`
	WarmDays int                  `json:"warmDays,omitempty"`
	Counts   PlacementCounts      `json:"counts"`
	MedianMs *int64               `json:"medianMs,omitempty"`
	Fastest  *PlacementTiming     `json:"fastest,omitempty"`
	Slowest  *PlacementTiming     `json:"slowest,omitempty"`
	Auth     PlacementAuthSummary `json:"auth"`
	Cost     float64              `json:"cost"`
}

PlacementProviderResult is one provider's copies in a test.

type PlacementReconnectInput

type PlacementReconnectInput struct {
	Host     string `json:"host,omitempty" maxLength:"253"`
	Port     int    `json:"port,omitempty" minimum:"1" maximum:"65535"`
	Username string `json:"username,omitempty" maxLength:"254"`
	Password string `json:"password" minLength:"1" maxLength:"500"`
}

PlacementReconnectInput reconnects a seed with a new password.

type PlacementResultSeed

type PlacementResultSeed struct {
	ID           string     `json:"id,omitempty"`
	Email        string     `json:"email"`
	Provider     string     `json:"provider"`
	ProviderName string     `json:"providerName"`
	Position     int        `json:"position"`
	Status       string     `json:"status" doc:"The seed's status now (removed when it's gone)"`
	StatusAt     *time.Time `json:"statusAt,omitempty"`
}

PlacementResultSeed is a row of the matrix.

type PlacementRouteShare

type PlacementRouteShare struct {
	ProviderID string   `json:"providerId"`
	Seeds      []string `json:"seeds"`
	// Reasons say why: "condition:outlook", "split:90", "default", "fallback".
	Reasons []string `json:"reasons"`
	// Fallback is the provider the route falls back to.
	Fallback string `json:"fallback,omitempty"`
	// Matched are the seeds a condition picked this provider for; the
	// rest came by a split or as the route's primary.
	Matched []string `json:"matched"`
}

PlacementRouteShare is the route as configured, for one provider.

type PlacementRunInput

type PlacementRunInput struct {
	Content PlacementContentRef `json:"content"`
	// Variant is the A/B variant, Language the language version ("" for
	// the source), TestData a transactional template's test data set
	// ("" for the fallbacks, or its first set with Personalization data).
	Variant string `json:"variant,omitempty" maxLength:"8"`
	// Version is a conditional-content version's number (X11); 0 sends
	// the one with the most recipients.
	Version         int    `json:"version,omitempty" minimum:"0" doc:"A conditional-content version's number; 0 picks the one with the most recipients"`
	Language        string `json:"language,omitempty" maxLength:"16"`
	TestData        string `json:"testData,omitempty" maxLength:"120"`
	Personalization string `` /* 149-byte string literal not displayed */
	// Through: the route as configured, one provider, or several compared.
	Through   string   `json:"through" enum:"route,provider,compare"`
	Providers []string `json:"providers,omitempty" maxItems:"6"`
	SenderID  string   `json:"senderId,omitempty"`
	// Seeds are the chosen seeds; empty means every connected seed.
	Seeds  []string `json:"seeds,omitempty" maxItems:"100"`
	Origin string   `json:"origin,omitempty" enum:"placement,review,composer,warmup,template,"`
	// contains filtered or unexported fields
}

PlacementRunInput is the Run a placement test dialog's choices.

type PlacementSeedCheck

type PlacementSeedCheck struct {
	Seed    PlacementSeedView `json:"seed"`
	Folders []PlacementFolder `json:"folders"`
}

PlacementSeedCheck is "Check passed · seed added": signed in, and the folders found.

type PlacementSeedChoice

type PlacementSeedChoice struct {
	ID           string     `json:"id"`
	Email        string     `json:"email"`
	Provider     string     `json:"provider"`
	ProviderName string     `json:"providerName"`
	Status       string     `json:"status"`
	StatusAt     *time.Time `json:"statusAt,omitempty"`
	Selected     bool       `json:"selected"`
}

PlacementSeedChoice is a seed in the dialog.

type PlacementSeedInput

type PlacementSeedInput struct {
	Provider string `json:"provider" enum:"gmail,google_workspace,outlook,microsoft_365,yahoo,aol,icloud,gmx,webde"`
	Email    string `json:"email" format:"email" maxLength:"254"`
	Host     string `json:"host,omitempty" maxLength:"253"`
	Port     int    `json:"port,omitempty" minimum:"1" maximum:"65535"`
	Username string `json:"username,omitempty" maxLength:"254"`
	Password string `json:"password" minLength:"1" maxLength:"500"`
}

PlacementSeedInput adds or reconnects a seed with an IMAP password.

type PlacementSeedList

type PlacementSeedList struct {
	Seeds       []PlacementSeedView     `json:"seeds"`
	Attention   int                     `json:"attention" doc:"Seeds whose sign-in failed or expired"`
	Connected   int                     `json:"connected"`
	DeleteAfter string                  `json:"deleteAfter" enum:"24h,finished,never"`
	Providers   []PlacementSeedProvider `json:"providers"`
	// OAuth: which of the instance's sign-in apps can connect seeds.
	OAuthGoogle    bool     `json:"oauthGoogle"`
	OAuthMicrosoft bool     `json:"oauthMicrosoft"`
	RedirectURI    string   `json:"redirectUri"`
	CanManage      bool     `json:"canManage"`
	ManageHelpers  []string `json:"manageHelpers"`
	CanRun         bool     `json:"canRun"`
	RunHelpers     []string `json:"runHelpers"`
}

PlacementSeedList is Placement tests › Seed mailboxes.

type PlacementSeedProvider

type PlacementSeedProvider struct {
	Key           string   `json:"key"`
	Name          string   `json:"name"`
	Company       string   `json:"company" doc:"Who runs the mailboxes (Apple for iCloud)"`
	Host          string   `json:"host"`
	Port          int      `json:"port"`
	OAuth         string   `json:"oauth,omitempty" enum:"google,microsoft,"`
	Password      string   `json:"password"`
	UsernameLabel string   `json:"usernameLabel"`
	PasswordHelp  string   `json:"passwordHelp,omitempty"`
	IMAPHelp      string   `json:"imapHelp,omitempty"`
	InboxName     string   `json:"inboxName"`
	SpamName      string   `json:"spamName"`
	Tabs          []string `json:"tabs"`
}

PlacementSeedProvider is a mailbox provider in the add dialog.

type PlacementSeedView

type PlacementSeedView struct {
	ID           string `json:"id"`
	Email        string `json:"email"`
	Provider     string `json:"provider" enum:"gmail,google_workspace,outlook,microsoft_365,yahoo,aol,icloud,gmx,webde"`
	ProviderName string `json:"providerName"`
	// Company runs the mailbox (Apple); Password is what it calls the
	// IMAP password (App-specific password).
	Company       string            `json:"company"`
	PasswordLabel string            `json:"passwordLabel"`
	Auth          string            `json:"auth" enum:"password,oauth"`
	Status        string            `json:"status" enum:"connected,expired,failed,unchecked"`
	StatusAt      *time.Time        `json:"statusAt,omitempty"`
	CheckedAt     *time.Time        `json:"checkedAt,omitempty"`
	Folders       []PlacementFolder `json:"folders"`
	LastUsedAt    *time.Time        `json:"lastUsedAt,omitempty"`
	LastTestID    string            `json:"lastTestId,omitempty"`
	LastTest      string            `json:"lastTest,omitempty"`
	AddedBy       string            `json:"addedBy"`
	AddedAt       time.Time         `json:"addedAt"`
	// The IMAP server and sign-in, filled in again when reconnecting.
	Host     string `json:"host,omitempty"`
	Port     int    `json:"port,omitempty"`
	Username string `json:"username,omitempty"`
}

PlacementSeedView is one seed mailbox. Its password or tokens are never returned.

type PlacementSenderOption

type PlacementSenderOption struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Email    string `json:"email"`
	Domain   string `json:"domain"`
	Verified bool   `json:"verified" doc:"Verified on every provider the test uses"`
	Default  bool   `json:"default"`
}

PlacementSenderOption is a sender of the stream.

type PlacementSettingsInput

type PlacementSettingsInput struct {
	DeleteAfter string `json:"deleteAfter" enum:"24h,finished,never"`
}

PlacementSettingsInput sets when copies are deleted from the seeds.

type PlacementTestDetail

type PlacementTestDetail struct {
	PlacementTestRow
	Variant          string `json:"variant,omitempty"`
	Language         string `json:"language,omitempty"`
	FallbackGreeting string `json:"fallbackGreeting,omitempty"`
	// ConditionalVersion is the conditional-content version sent (0:
	// none), ConditionalShows what it shows.
	ConditionalVersion int    `json:"conditionalVersion,omitempty"`
	ConditionalShows   string `json:"conditionalShows,omitempty"`
	Subject            string `json:"subject"`
	FromName           string `json:"fromName"`
	FromEmail          string `json:"fromEmail"`
	Stream             string `json:"stream"`
	// Rounds is how many copies each seed got (one per compared provider),
	// GapMinutes how far apart.
	Rounds     int `json:"rounds"`
	GapMinutes int `json:"gapMinutes"`
	// Copies in the seeds: the setting, when they go, and when they went.
	DeleteAfter     string     `json:"deleteAfter" enum:"24h,finished,never"`
	DeleteAt        *time.Time `json:"deleteAt,omitempty"`
	CopiesDeletedAt *time.Time `json:"copiesDeletedAt,omitempty"`
	CopiesDeletedBy string     `json:"copiesDeletedBy,omitempty"`
	StoppedAt       *time.Time `json:"stoppedAt,omitempty"`
	StoppedBy       string     `json:"stoppedBy,omitempty"`
	// FinishReason: every copy was found, the 15 minutes ran out, or a person stopped it.
	FinishReason string                `json:"finishReason,omitempty" enum:"all_found,timeout,stopped,"`
	Seeds        []PlacementResultSeed `json:"seeds"`
	Copies       []PlacementCopyView   `json:"copies"`
	Guidance     []PlacementGuidance   `json:"guidance"`
	HostRepute   bool                  `json:"hostRepute"`
	CanRun       bool                  `json:"canRun"`
	RunHelpers   []string              `json:"runHelpers"`
}

PlacementTestDetail is one test: what it sent, how, and where each copy landed.

type PlacementTestList

type PlacementTestList struct {
	Tests []PlacementTestRow `json:"tests"`
	// Seeds: connected and all, and the ones whose sign-in failed or expired.
	SeedsConnected int                 `json:"seedsConnected"`
	SeedsTotal     int                 `json:"seedsTotal"`
	Attention      []PlacementSeedView `json:"attention"`
	DeleteAfter    string              `json:"deleteAfter" enum:"24h,finished,never"`
	// Filters: the providers tests went through, and who started them.
	Providers     []PlacementFacet `json:"providers"`
	Starters      []PlacementFacet `json:"starters"`
	CanRun        bool             `json:"canRun"`
	RunHelpers    []string         `json:"runHelpers"`
	CanManage     bool             `json:"canManage"`
	ManageHelpers []string         `json:"manageHelpers"`
}

PlacementTestList is Deliverability › Placement tests.

type PlacementTestRow

type PlacementTestRow struct {
	ID             string     `json:"id"`
	Name           string     `json:"name"`
	ContentKind    string     `json:"contentKind" enum:"campaign,template,digest,transactional"`
	ContentID      string     `json:"contentId,omitempty"`
	ContentName    string     `json:"contentName"`
	ContentNote    string     `json:"contentNote" doc:"draft, scheduled, sent, template or the transactional template's key"`
	ContentKey     string     `json:"contentKey,omitempty"`
	ContentVersion int        `json:"contentVersion,omitempty"`
	ContentAt      *time.Time `json:"contentAt,omitempty" doc:"When the campaign is scheduled or was sent"`
	// Personalization is the test data set ("" for the fallbacks).
	Personalization string                    `json:"personalization"`
	Origin          string                    `json:"origin" enum:"placement,review,composer,warmup,template"`
	Through         string                    `json:"through" enum:"route,provider,compare"`
	Status          string                    `json:"status" enum:"sending,waiting,finished,stopped"`
	StartedAt       time.Time                 `json:"startedAt"`
	StartedBy       string                    `json:"startedBy"`
	StartedByID     string                    `json:"startedById,omitempty"`
	StartedByColor  string                    `json:"startedByColor,omitempty"`
	LastSentAt      *time.Time                `json:"lastSentAt,omitempty"`
	WaitUntil       *time.Time                `json:"waitUntil,omitempty" doc:"Copies missing then are Not arrived"`
	LateUntil       *time.Time                `json:"lateUntil,omitempty" doc:"Late copies found until then update the result"`
	FinishedAt      *time.Time                `json:"finishedAt,omitempty"`
	Providers       []PlacementProviderResult `json:"providers"`
	// Mailboxes are the copies per mailbox provider (SR-9).
	Mailboxes []PlacementMailboxResult `json:"mailboxes"`
	Counts    PlacementCounts          `json:"counts"`
}

PlacementTestRow is a test in the list and the trend.

type PlacementTestValue

type PlacementTestValue struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

PlacementTestValue is a variable of the chosen test data set.

type PlacementTiming

type PlacementTiming struct {
	Ms               int64  `json:"ms"`
	SeedProvider     string `json:"seedProvider"`
	SeedProviderName string `json:"seedProviderName"`
	Folder           string `json:"folder" enum:"inbox,tab,spam"`
	FolderName       string `json:"folderName"`
}

PlacementTiming is a copy's time to arrive, with where it went.

type PlacementVariant

type PlacementVariant struct {
	Key     string `json:"key"`
	Subject string `json:"subject"`
}

PlacementVariant is an A/B variant of the email.

type Readiness

type Readiness interface {
	Latest(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (ReadinessSummary, bool)
}

Readiness is the latest Send Readiness run of a campaign, for the guidance.

type ReadinessSummary

type ReadinessSummary struct {
	Passed, Warnings, Blocks int
	Blocking, Evidence       []string
}

ReadinessSummary is a run's counts and blocking findings: their labels and one sentence of evidence each.

type SendArgs

type SendArgs struct {
	TestID uuid.UUID `json:"testId"`
}

SendArgs hands a test's due copies to their providers.

func (SendArgs) Kind

func (SendArgs) Kind() string

Kind implements river.JobArgs.

type SendWorker

type SendWorker struct {
	river.WorkerDefaults[SendArgs]
	Svc *Service
}

SendWorker runs SendArgs.

func (*SendWorker) Work

func (w *SendWorker) Work(ctx context.Context, job *river.Job[SendArgs]) error

Work implements river.Worker; a comparison's later rounds snooze until due.

type Sender

type Sender interface {
	Send(ctx context.Context, p store.Provider, msg providers.Message, kind string) (systemmail.Delivery, error)
}

Sender hands one copy to a provider (systemmail.Deliverer).

type Service

type Service struct {
	Pool  *pgxpool.Pool
	Q     *store.Queries
	Audit *audit.Logger
	Box   *secrets.Box
	Log   *slog.Logger
	// Deliver hands copies to providers through the normal sending path.
	Deliver       Sender
	Links         *linktoken.Signer
	URLs          publicurl.Builder
	Transactional Transactional
	// Digests builds a recurring digest's next issue (nil: no digests).
	Digests Digests
	// Visibility gives conditional-content versions (nil: every block).
	Visibility Visibility
	Apps       MailApps
	Readiness  Readiness
	Notify     Notifier
	// LangOf is a member's language, for what ReputeCast writes to them.
	LangOf func(ctx context.Context, userID uuid.UUID) i18n.Lang
	// Jobs is River's client (read lazily); nil or Inline runs work in
	// the request (tests).
	Jobs   func() *jobs.Client
	Inline bool
	// Guard dials seed mailboxes' IMAP servers (user-supplied hosts).
	Guard netguard.Policy
	// HTTP calls Microsoft Graph and the OAuth token endpoints.
	HTTP *http.Client
	// OAuthEndpoints replaces Google's and Microsoft's (tests).
	OAuthEndpoints *Endpoints
	// GraphURL replaces Microsoft Graph's root (tests).
	GraphURL string
	// InsecureIMAP dials test IMAP servers without TLS; IMAPHost and
	// IMAPPort replace the fixed servers of OAuth seeds (tests).
	InsecureIMAP bool
	IMAPHost     string
	IMAPPort     int
	Now          func() time.Time
}

Service is the placement domain.

func (*Service) AddSeed

AddSeed checks an IMAP sign-in and adds the seed (audited).

func (*Service) Check

func (s *Service) Check(ctx context.Context, id uuid.UUID) error

Check signs in to the seeds of a test, finds its copies by their test token and records where each landed. A test waiting for its copies finishes when every copy is found or 15 minutes after the last hand-off; afterwards it keeps looking for late copies for an hour.

func (*Service) CheckOpen

func (s *Service) CheckOpen(ctx context.Context) error

CheckOpen looks for the copies of the open tests, one test at a time.

func (*Service) CopyDetail

func (s *Service) CopyDetail(ctx context.Context, ws *store.Workspace, testID, copyID uuid.UUID) (PlacementCopyDetail, error)

CopyDetail returns one copy.

func (*Service) DeleteCopiesNow

func (s *Service) DeleteCopiesNow(ctx context.Context, ws *store.Workspace, id uuid.UUID) (PlacementTestDetail, error)

DeleteCopiesNow deletes a test's copies from the seeds (audited).

func (*Service) DeleteDue

func (s *Service) DeleteDue(ctx context.Context) error

DeleteDue deletes the copies whose time has come.

func (*Service) OAuthCallback

func (s *Service) OAuthCallback(ctx context.Context, user *store.User, self, state, code, oauthErr, oauthErrDesc string) string

OAuthCallback finishes a consent: it trades the code for tokens, checks the mailbox with them and adds (or reconnects) the seed. It returns the app path to send the browser to. The signed-in person must be the one who started it and still hold placement:manage in the workspace.

func (*Service) Plan

Plan says what a test would send, for the dialog.

func (*Service) Reconnect

Reconnect checks a new password and saves it (audited).

func (*Service) RemoveSeed

func (s *Service) RemoveSeed(ctx context.Context, ws *store.Workspace, id uuid.UUID) error

RemoveSeed removes a seed and its password or tokens. Copies of past tests stay in the mailbox; results keep the seed's row.

func (*Service) RunAgain

func (s *Service) RunAgain(ctx context.Context, ws *store.Workspace, testID uuid.UUID) (PlacementTestDetail, error)

RunAgain starts a new test with an earlier test's content and choices, to every seed connected now.

func (*Service) SearchContent

func (s *Service) SearchContent(ctx context.Context, ws *store.Workspace, q string) (PlacementContentList, error)

SearchContent finds campaigns, templates and transactional templates to test.

func (*Service) Seeds

Seeds lists the seed mailboxes.

func (*Service) SendDue

func (s *Service) SendDue(ctx context.Context, id uuid.UUID) (*time.Time, error)

SendDue sends the copies whose time has come and returns when the next round is due (nil when every copy is out).

func (*Service) SetSettings

SetSettings saves when copies are deleted (audited).

func (*Service) Start

Start creates a test and its copies and starts sending (audited).

func (*Service) StartOAuth

StartOAuth begins Google's or Microsoft's consent for a seed, with PKCE and a single-use state bound to the person and the workspace.

func (*Service) Stop

Stop ends a test now: copies not found yet are Not arrived and aren't looked for any more (audited).

func (*Service) Test

Test returns one test with its matrix and guidance.

func (*Service) Tests

Tests lists the workspace's tests, newest first (every one started by a person).

func (s *Service) TrackedLink(ctx context.Context, copyID uuid.UUID, position int) (string, bool)

TrackedLink resolves a copy's tracked link to the test's own link at that position (tracking redirects clicks of copies without counting them).

type Transactional

type Transactional interface {
	RenderLive(ctx context.Context, ws *store.Workspace, key string, data map[string]any, to string) (subject, html, text string, version int, err error)
}

Transactional renders a transactional template's live version with test data.

type Visibility

type Visibility interface {
	Versions(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) ([]ConditionalVersion, error)
	Cut(html, hidden string) string
}

Visibility gives a campaign's conditional-content versions and cuts one out of the compiled HTML (internal/visibility, X11).

Directories

Path Synopsis
Package seedbox reads the seed mailboxes of placement tests: it signs in (an IMAP password, IMAP with XOAUTH2, or Microsoft Graph with OAuth), finds the folders a copy can land in, finds copies by their test token, tells which folder or tab each one is in, and deletes them afterwards.
Package seedbox reads the seed mailboxes of placement tests: it signs in (an IMAP password, IMAP with XOAUTH2, or Microsoft Graph with OAuth), finds the folders a copy can land in, finds copies by their test token, tells which folder or tab each one is in, and deletes them afterwards.
seedtest
Package seedtest runs an in-process IMAP server for placement tests: seed mailboxes with an inbox, a spam folder marked \Junk (as the real providers mark theirs) and a trash, password and XOAUTH2 sign-in, and Gmail's X-GM-RAW category search for the tabs.
Package seedtest runs an in-process IMAP server for placement tests: seed mailboxes with an inbox, a spam folder marked \Junk (as the real providers mark theirs) and a trash, password and XOAUTH2 sign-in, and Gmail's X-GM-RAW category search for the tabs.

Jump to

Keyboard shortcuts

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