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
- Variables
- func DemoAuth(raw string) json.RawMessage
- func DemoFolders(provider, auth string) []seedbox.Folder
- func DemoHeaders(m DemoMail) string
- func DemoHop(raw string) json.RawMessage
- func Helpers(ctx context.Context, q *store.Queries, wsID uuid.UUID, perm authz.Permission) []string
- func NameIn(l i18n.Lang, name, content string) string
- func Register(h huma.API, s *Service)
- func RegisterJobs(reg *jobs.Registry, s *Service)
- func SealCredentials(s interface{ ... }, seedID uuid.UUID, password string, demo bool) ([]byte, error)
- type CheckArgs
- type CheckWorker
- type ConditionalVersion
- type DeleteArgs
- type DeleteWorker
- type DemoMail
- type DemoOutcome
- type Digests
- type Endpoints
- type MailApp
- type MailApps
- type Notifier
- type PlacementAuthCheck
- type PlacementAuthCount
- type PlacementAuthReadiness
- type PlacementAuthSummary
- type PlacementConditionalVersion
- type PlacementContentList
- type PlacementContentOption
- type PlacementContentRef
- type PlacementContentView
- type PlacementCopyCost
- type PlacementCopyDetail
- type PlacementCopyView
- type PlacementCounts
- type PlacementEarlier
- type PlacementEvent
- type PlacementFacet
- type PlacementFolder
- type PlacementGuidance
- type PlacementLanguage
- type PlacementNotChecked
- type PlacementOAuthInput
- type PlacementOAuthStart
- type PlacementOther
- type PlacementPlan
- type PlacementProviderOption
- type PlacementProviderResult
- type PlacementReconnectInput
- type PlacementResultSeed
- type PlacementRouteShare
- type PlacementRunInput
- type PlacementSeedCheck
- type PlacementSeedChoice
- type PlacementSeedInput
- type PlacementSeedList
- type PlacementSeedProvider
- type PlacementSeedView
- type PlacementSenderOption
- type PlacementSettingsInput
- type PlacementTestDetail
- type PlacementTestList
- type PlacementTestRow
- type PlacementTestValue
- type PlacementTiming
- type PlacementVariant
- type Readiness
- type ReadinessSummary
- type SendArgs
- type SendWorker
- type Sender
- type Service
- func (s *Service) AddSeed(ctx context.Context, ws *store.Workspace, in PlacementSeedInput) (PlacementSeedCheck, error)
- func (s *Service) Check(ctx context.Context, id uuid.UUID) error
- func (s *Service) CheckOpen(ctx context.Context) error
- func (s *Service) CopyDetail(ctx context.Context, ws *store.Workspace, testID, copyID uuid.UUID) (PlacementCopyDetail, error)
- func (s *Service) DeleteCopiesNow(ctx context.Context, ws *store.Workspace, id uuid.UUID) (PlacementTestDetail, error)
- func (s *Service) DeleteDue(ctx context.Context) error
- func (s *Service) OAuthCallback(ctx context.Context, user *store.User, ...) string
- func (s *Service) Plan(ctx context.Context, ws *store.Workspace, in PlacementRunInput) (PlacementPlan, error)
- func (s *Service) Reconnect(ctx context.Context, ws *store.Workspace, id uuid.UUID, ...) (PlacementSeedCheck, error)
- func (s *Service) RemoveSeed(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) RunAgain(ctx context.Context, ws *store.Workspace, testID uuid.UUID) (PlacementTestDetail, error)
- func (s *Service) SearchContent(ctx context.Context, ws *store.Workspace, q string) (PlacementContentList, error)
- func (s *Service) Seeds(ctx context.Context, ws *store.Workspace) (PlacementSeedList, error)
- func (s *Service) SendDue(ctx context.Context, id uuid.UUID) (*time.Time, error)
- func (s *Service) SetSettings(ctx context.Context, ws *store.Workspace, in PlacementSettingsInput) (PlacementSettingsInput, error)
- func (s *Service) Start(ctx context.Context, ws *store.Workspace, in PlacementRunInput) (PlacementTestDetail, error)
- func (s *Service) StartOAuth(ctx context.Context, ws *store.Workspace, in PlacementOAuthInput) (PlacementOAuthStart, error)
- func (s *Service) Stop(ctx context.Context, ws *store.Workspace, id uuid.UUID) (PlacementTestDetail, error)
- func (s *Service) Test(ctx context.Context, ws *store.Workspace, id uuid.UUID) (PlacementTestDetail, error)
- func (s *Service) Tests(ctx context.Context, ws *store.Workspace) (PlacementTestList, error)
- func (s *Service) TrackedLink(ctx context.Context, copyID uuid.UUID, position int) (string, bool)
- type Transactional
- type Visibility
Constants ¶
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).
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.
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.
const Kind = "placement"
Kind is the messages.kind of a copy.
Variables ¶
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") )
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 ¶
DemoFolders are the folders a seed of provider shows (the seeder uses them too).
func DemoHeaders ¶
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 Helpers ¶
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 ¶
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 RegisterJobs ¶
RegisterJobs adds the workers and the periodic jobs.
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.
type CheckWorker ¶
type CheckWorker struct {
river.WorkerDefaults[CheckArgs]
Svc *Service
}
CheckWorker runs CheckArgs.
type ConditionalVersion ¶
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.
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 ¶
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 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 ¶
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 ¶
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 ¶
PlacementLanguage is a language version of the email.
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 {
Reasons []string `json:"reasons"`
Fallback string `json:"fallback,omitempty"`
// 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"`
Counts PlacementCounts `json:"counts"`
}
PlacementTestRow is a test in the list and the trend.
type PlacementTestValue ¶
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 ¶
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 ¶
ReadinessSummary is a run's counts and blocking findings: their labels and one sentence of evidence each.
type SendWorker ¶
type SendWorker struct {
river.WorkerDefaults[SendArgs]
Svc *Service
}
SendWorker runs SendArgs.
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 ¶
func (s *Service) AddSeed(ctx context.Context, ws *store.Workspace, in PlacementSeedInput) (PlacementSeedCheck, error)
AddSeed checks an IMAP sign-in and adds the seed (audited).
func (*Service) Check ¶
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) 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) 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 ¶
func (s *Service) Plan(ctx context.Context, ws *store.Workspace, in PlacementRunInput) (PlacementPlan, error)
Plan says what a test would send, for the dialog.
func (*Service) Reconnect ¶
func (s *Service) Reconnect(ctx context.Context, ws *store.Workspace, id uuid.UUID, in PlacementReconnectInput) (PlacementSeedCheck, error)
Reconnect checks a new password and saves it (audited).
func (*Service) RemoveSeed ¶
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) SendDue ¶
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 ¶
func (s *Service) SetSettings(ctx context.Context, ws *store.Workspace, in PlacementSettingsInput) (PlacementSettingsInput, error)
SetSettings saves when copies are deleted (audited).
func (*Service) Start ¶
func (s *Service) Start(ctx context.Context, ws *store.Workspace, in PlacementRunInput) (PlacementTestDetail, error)
Start creates a test and its copies and starts sending (audited).
func (*Service) StartOAuth ¶
func (s *Service) StartOAuth(ctx context.Context, ws *store.Workspace, in PlacementOAuthInput) (PlacementOAuthStart, error)
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 ¶
func (s *Service) Stop(ctx context.Context, ws *store.Workspace, id uuid.UUID) (PlacementTestDetail, error)
Stop ends a test now: copies not found yet are Not arrived and aren't looked for any more (audited).
func (*Service) Test ¶
func (s *Service) Test(ctx context.Context, ws *store.Workspace, id uuid.UUID) (PlacementTestDetail, error)
Test returns one test with its matrix and guidance.
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).
Source Files
¶
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. |