Documentation
¶
Overview ¶
Package reports builds the campaign report (spec 7.7, honest analytics 5.5) from campaign_counters, its exports and read-only report links, whose public page shows the same aggregate numbers and nothing else.
Index ¶
- Constants
- func Register(h huma.API, s *Service)
- type CampaignReport
- type ExportInput
- type FinalAlertsArgs
- type FinalAlertsWorker
- type GeoIP
- type Inserter
- type Limiter
- type RebuildArgs
- type RebuildSweepArgs
- type RebuildSweepWorker
- type RebuildWorker
- type ReportABTest
- type ReportABVariant
- type ReportBacklogProvider
- type ReportBlockedRetry
- type ReportBounceDiagnostic
- type ReportBounceReview
- type ReportBounceRow
- type ReportBounceTable
- type ReportBreakdown
- type ReportCampaignInfo
- type ReportCampaignRef
- type ReportClickMap
- type ReportCodeCount
- type ReportComparison
- type ReportComparisons
- type ReportDimRow
- type ReportEngagement
- type ReportEngagementPoint
- type ReportExport
- type ReportFinalAlert
- type ReportGrowth
- type ReportHeadline
- type ReportIngestBacklog
- type ReportInsight
- type ReportLink
- type ReportLinkGroup
- type ReportLinkRow
- type ReportMailboxRow
- type ReportNotSent
- type ReportPath
- type ReportProviderColumn
- type ReportProviderCount
- type ReportProviderTable
- type ReportRates
- type ReportRetryCampaign
- type ReportRollout
- type ReportShareIncludes
- type ReportShareLink
- type ReportShareList
- type ReportSummarySetting
- type ReportSuppressResult
- type ReportTimeBucket
- type ReportUnsubscribeReason
- type ReportUnsubscribes
- type ReportVariantClickMap
- type Service
- func (s *Service) BounceReview(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, typeKey string) (ReportBounceReview, error)
- func (s *Service) CreateShare(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, in ShareInput) (ReportShareLink, error)
- func (s *Service) Export(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, format string) (ReportExport, error)
- func (s *Service) FinalAlert(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (ReportFinalAlert, error)
- func (s *Service) QueueSummaries(ctx context.Context) (int, error)
- func (s *Service) Report(ctx context.Context, ws *store.Workspace, id uuid.UUID) (CampaignReport, error)
- func (s *Service) ReportIn(ctx context.Context, ws *store.Workspace, id uuid.UUID, lang string) (CampaignReport, error)
- func (s *Service) RevokeShare(ctx context.Context, ws *store.Workspace, campaignID, shareID uuid.UUID) error
- func (s *Service) SendFinalAlerts(ctx context.Context) (int, error)
- func (s *Service) SetFinalAlert(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, on bool) (ReportFinalAlert, error)
- func (s *Service) SetSummary(ctx context.Context, ws *store.Workspace, freq string) (ReportSummarySetting, error)
- func (s *Service) Shared(ctx context.Context, token, client string) (SharedCampaignReport, error)
- func (s *Service) Shares(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (ReportShareList, error)
- func (s *Service) Summary(ctx context.Context, ws *store.Workspace) (ReportSummarySetting, error)
- func (s *Service) SuppressBounces(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, typeKey string) (ReportSuppressResult, error)
- type ShareInput
- type SharedCampaignReport
- type SummaryArgs
- type SummarySendArgs
- type SummarySendWorker
- type SummaryWorker
- type Suppressor
Constants ¶
const ( )
DefaultShareDays is how long a read-only link works unless the person who makes it chooses otherwise, and MaxShareDays the longest they can choose (review AN-16).
const BacklogAfter = 5 * time.Minute
BacklogAfter is how old the oldest unprocessed provider event must be before the report says part of it is behind.
const CompareIssues = 6
CompareIssues is how many earlier issues the medians are of.
const FinalAfter = 72 * time.Hour
FinalAfter is how long after a send ends opens and clicks keep counting before the report calls its results final.
HotShare is the share of clicks (percent) from which a link's bubble is red.
const LinkThreshold = 5.0
LinkThreshold is the share of clicks (percent) under which a link is grouped as "Other" on the click map.
const MaxActiveLinks = 10
MaxActiveLinks caps the read-only links a campaign can have at once.
const MinPlace = 5
MinPlace is the fewest human opens a city needs to be named (and a country, on a read-only link): fewer fold into "other", so a small place can't point at a few readers.
const OutcomeUnrecorded = "unrecorded"
OutcomeUnrecorded is the outcome of a test decided before the sending engine kept its decisions: the winner is known, what decided it isn't.
const TopPlaces = 20
TopPlaces is how many countries and cities the report lists before it folds the rest into "other".
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CampaignReport ¶
type CampaignReport struct {
Campaign ReportCampaignInfo `json:"campaign"`
Headline ReportHeadline `json:"headline"`
// Comparisons are the tiles' changes against the median of the last
// issues (review AN-11).
Comparisons ReportComparisons `json:"comparisons"`
// Insights are worked out from the report's numbers, each with what to
// do about it.
Insights []ReportInsight `json:"insights"`
// Growth is the issue's new subscribers and web views (review AN-12);
// its upgrades and revenue are the campaign's revenue (Earn).
Growth ReportGrowth `json:"growth"`
Engagement ReportEngagement `json:"engagement"`
ClickMap ReportClickMap `json:"clickMap"`
Mailboxes []ReportMailboxRow `json:"mailboxes"`
// Breakdown is "Mail clients and devices", "Countries" and "When
// people opened" (M57 G-12).
Breakdown ReportBreakdown `json:"breakdown"`
Providers ReportProviderTable `json:"providers"`
Bounces ReportBounceTable `json:"bounces"`
Unsubscribes ReportUnsubscribes `json:"unsubscribes"`
ABTest *ReportABTest `json:"abTest,omitempty"`
Backlog *ReportIngestBacklog `json:"backlog,omitempty"`
// Languages is "Results per language", for a campaign sent in more than
// one language.
Languages *languages.ReportLanguages `json:"languages,omitempty"`
// NotSent is set for campaigns that haven't sent anything yet.
NotSent *ReportNotSent `json:"notSent,omitempty"`
}
CampaignReport is the campaign report (spec 7.7, honest analytics 5.5). It only ever holds aggregate numbers: no contact address or other personal data, so the same document serves the read-only shared link.
type ExportInput ¶
type ExportInput struct {
// Format: csv returns the file; pdf records the export of the printable
// report, which the browser saves as a PDF.
Format string `json:"format" enum:"csv,pdf"`
}
ExportInput asks for an export of the report.
type FinalAlertsArgs ¶
type FinalAlertsArgs struct{}
FinalAlertsArgs sends the alerts that are due (periodic).
func (FinalAlertsArgs) InsertOpts ¶
func (FinalAlertsArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type FinalAlertsWorker ¶
type FinalAlertsWorker struct {
river.WorkerDefaults[FinalAlertsArgs]
S *Service
}
FinalAlertsWorker runs FinalAlertsArgs.
func (*FinalAlertsWorker) Work ¶
func (w *FinalAlertsWorker) Work(ctx context.Context, _ *river.Job[FinalAlertsArgs]) error
Work implements river.Worker.
type GeoIP ¶
type GeoIP interface{ Loaded() bool }
GeoIP says whether the server has a GeoIP database loaded (geoip.DB): without one, no message gets a country or a city.
type Inserter ¶
type Inserter interface {
InsertTx(ctx context.Context, tx pgx.Tx, args river.JobArgs, opts *river.InsertOpts) (*rivertype.JobInsertResult, error)
}
Inserter queues jobs in a transaction (River's client).
type Limiter ¶
type Limiter struct {
// Requests per Window per address.
Requests int
// Misses (unknown or revoked links) per MissWindow per address.
Misses int
Window time.Duration
MissWindow time.Duration
// contains filtered or unexported fields
}
Limiter is a fixed-window rate limiter per client address for the public report endpoint: a cap on requests, and a much lower cap on lookups of links that don't exist, so guessing tokens is pointless.
func NewLimiter ¶
func NewLimiter() *Limiter
NewLimiter returns the default limits: 60 requests a minute and 20 unknown links per 10 minutes per address.
type RebuildArgs ¶
RebuildArgs rebuilds one campaign's counters.
func (RebuildArgs) InsertOpts ¶
func (RebuildArgs) InsertOpts() river.InsertOpts
InsertOpts puts rebuilds on the maintenance queue, one per campaign at a time.
type RebuildSweepArgs ¶
type RebuildSweepArgs struct{}
RebuildSweepArgs queues the rebuilds that are due (periodic).
func (RebuildSweepArgs) InsertOpts ¶
func (RebuildSweepArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type RebuildSweepWorker ¶
type RebuildSweepWorker struct {
river.WorkerDefaults[RebuildSweepArgs]
Q *store.Queries
Jobs func() *jobs.Client
Now func() time.Time
}
RebuildSweepWorker runs RebuildSweepArgs: campaigns whose results became final, or that were counted with older rules, a few at a time.
func (*RebuildSweepWorker) Work ¶
func (w *RebuildSweepWorker) Work(ctx context.Context, _ *river.Job[RebuildSweepArgs]) error
Work implements river.Worker.
type RebuildWorker ¶
type RebuildWorker struct {
river.WorkerDefaults[RebuildArgs]
Pool *pgxpool.Pool
Now func() time.Time
}
RebuildWorker runs RebuildArgs.
func (*RebuildWorker) Timeout ¶
func (w *RebuildWorker) Timeout(*river.Job[RebuildArgs]) time.Duration
Timeout bounds one rebuild (a campaign of a few hundred thousand messages takes seconds).
func (*RebuildWorker) Work ¶
func (w *RebuildWorker) Work(ctx context.Context, job *river.Job[RebuildArgs]) error
Work implements river.Worker.
type ReportABTest ¶
type ReportABTest struct {
Kind string `json:"kind" enum:"subject,content,send_time"`
Label string `json:"label" doc:"subject line, content, send time"`
// Metric is human_opens (of measurable recipients) or clicks; machine
// and privacy-protected opens never count.
Metric string `json:"metric" enum:"human_opens,clicks"`
WindowHours float64 `json:"windowHours"`
DecidedAt *time.Time `json:"decidedAt,omitempty"`
// DecidedAfter is how many hours after the sample went out it was
// decided.
DecidedAfter *float64 `json:"decidedAfter,omitempty"`
// State: decided (a winner went out), testing (the window is open) or
// no_winner (no clear winner: the default went out).
State string `json:"state" enum:"decided,testing,no_winner"`
// Outcome is the decision: winner, not_significant, too_small, manual
// (a person picked) or unrecorded (decided before decisions were kept:
// the winner is known, its confidence isn't, so none is given); empty
// while testing.
Outcome string `json:"outcome,omitempty" enum:"winner,not_significant,too_small,manual,unrecorded,"`
// Winner is the variant the rest got; Default the test's default (A).
Winner string `json:"winner,omitempty"`
Default string `json:"default"`
Variants []ReportABVariant `json:"variants"`
// Leader and RunnerUp of the decision (or of the test so far).
Leader string `json:"leader,omitempty"`
RunnerUp string `json:"runnerUp,omitempty"`
// Lift is the leader's advantage on the metric, in percentage points.
Lift *float64 `json:"lift,omitempty"`
// PValue of the two-sided z-test; Confidence is 1 - p, in percent.
PValue *float64 `json:"pValue,omitempty"`
Confidence *float64 `json:"confidence,omitempty"`
Significant bool `json:"significant" doc:"Confidence reached the threshold, with enough recipients per variant"`
// MinSample is the fewest recipients each variant needed; Threshold the
// confidence a winner needed, in percent (95).
MinSample int64 `json:"minSample"`
Threshold float64 `json:"threshold"`
// Remaining recipients who got the variant after the test, and when.
Remaining int64 `json:"remaining"`
RolloutAt *time.Time `json:"rolloutAt,omitempty"`
// BarMax is the top of the bars' scale, in percent ("on a 0 to 10%
// scale").
BarMax float64 `json:"barMax"`
}
ReportABTest is "A/B test" with the confidence of the result: the sending engine's decision (internal/abstats: at least MinSample recipients per variant, a two-proportion z-test between the leader and the runner-up at the Threshold confidence; otherwise the default goes out), and each sample's results since.
type ReportABVariant ¶
type ReportABVariant struct {
Key string `json:"key"`
Label string `json:"label" doc:"The subject line, or what differs"`
// Default is the variant the rest get when the test has no clear
// winner (A).
Default bool `json:"default"`
// Recipients of the test sample.
Recipients int64 `json:"recipients"`
SamplePercent float64 `json:"samplePercent"`
// The sample's results so far (final after 72 hours): human opens of
// the measurable recipients, clicks and complaints of delivered.
HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
ClickRate *float64 `json:"clickRate,omitempty"`
ComplaintRate *float64 `json:"complaintRate,omitempty"`
// MetricRate is the rate on the test's metric now (the bar).
MetricRate *float64 `json:"metricRate,omitempty"`
// DecisionRate is the rate on the metric the decision was made on.
DecisionRate *float64 `json:"decisionRate,omitempty"`
// Eligible and Conversions are what the decision counted: recipients
// whose result could be measured, and how many converted.
Eligible int64 `json:"eligible"`
Conversions int64 `json:"conversions"`
// Winner is the variant the rest got (the leader, or the default
// without a clear winner).
Winner bool `json:"winner"`
// Remaining is how many recipients got this variant after the test.
Remaining int64 `json:"remaining"`
}
ReportABVariant is one variant of the A/B test: its test sample's results (the recipients who got it after the test are counted apart, as the remaining).
type ReportBacklogProvider ¶
type ReportBacklogProvider struct {
ProviderID string `json:"providerId"`
Name string `json:"name"`
Short string `json:"short"`
Feed string `json:"feed" doc:"How its events arrive: SNS, webhook, bounce mailbox"`
Waiting int64 `json:"waiting"`
Since time.Time `json:"since"`
}
ReportBacklogProvider is one provider whose events haven't been processed.
type ReportBlockedRetry ¶
type ReportBlockedRetry struct {
// Blocked counts the addresses blocked for the sender's reputation or
// policy, never delivered, that haven't had a retry; Recipients those
// of them a retry goes to now (still in the audience: not unsubscribed,
// suppressed or paused).
Blocked int64 `json:"blocked"`
Recipients int64 `json:"recipients"`
// Campaign is the retry, once made (a draft, or sent).
Campaign *ReportRetryCampaign `json:"campaign,omitempty"`
// a retry, which isn't retried again), not_finished (its send hasn't
// ended) or none_left (no address left to retry).
Unavailable string `json:"unavailable,omitempty" enum:"is_retry,not_finished,none_left,"`
// Of is the campaign a retry retries (is_retry).
Of *ReportCampaignRef `json:"of,omitempty"`
}
ReportBlockedRetry is what a retry of the blocked addresses would do, or the retry made already (review AN-7, R5.L5).
type ReportBounceDiagnostic ¶
type ReportBounceDiagnostic struct {
Provider string `json:"provider"`
Type string `json:"type"`
Code string `json:"code"`
Diagnostic string `json:"diagnostic"`
Count int64 `json:"count"`
}
ReportBounceDiagnostic is one provider message behind a bounce type.
type ReportBounceReview ¶
type ReportBounceReview struct {
Type string `json:"type"`
Label string `json:"label"`
Count int64 `json:"count"`
Unsuppressed int64 `json:"unsuppressed"`
Diagnostics []ReportBounceDiagnostic `json:"diagnostics"`
// Retry is "Retry after fixing", for blocks for the sender's
// reputation or policy (review AN-7); absent for other bounces.
Retry *ReportBlockedRetry `json:"retry,omitempty"`
}
ReportBounceReview is the Review dialog of a bounce type.
type ReportBounceRow ¶
type ReportBounceRow struct {
Type string `json:"type" enum:"unknown_user,domain_invalid,mailbox_full,deferral_expired,blocked,other"`
Label string `json:"label"`
Tone string `json:"tone" enum:"bad,warn,neutral"`
Count int64 `json:"count"`
Codes []ReportCodeCount `json:"codes"`
// Suppression: auto (every address was suppressed when it bounced),
// retry (soft bounces are retried next send), add (addresses aren't
// suppressed; a person can add them), review (look at the diagnostics
// first), suppressed (all of them are on the list now), investigate (a
// block for the sending IP or domain: the addresses are valid and stay
// on the list; never suppressed, review AN-7).
Suppression string `json:"suppression" enum:"auto,retry,add,review,suppressed,investigate"`
// Unsuppressed is how many bounced addresses aren't on the list.
Unsuppressed int64 `json:"unsuppressed"`
}
ReportBounceRow is one type of the shared bounce taxonomy.
type ReportBounceTable ¶
type ReportBounceTable struct {
Total int64 `json:"total"`
Rows []ReportBounceRow `json:"rows"`
}
ReportBounceTable is "Bounces by type".
type ReportBreakdown ¶
type ReportBreakdown struct {
// Measured is false for campaigns sent before ReputeCast recorded
// breakdowns and for imported history.
Measured bool `json:"measured"`
Clients []ReportDimRow `json:"clients"`
Systems []ReportDimRow `json:"systems"`
Devices []ReportDimRow `json:"devices"`
// Countries and Cities: the top 20 by human opens, the rest folded into
// "other"; cities with fewer than 5 human opens fold too. Read-only
// links show no cities.
Countries []ReportDimRow `json:"countries"`
Cities []ReportDimRow `json:"cities"`
// Located are the human opens whose country is known: Gmail's and
// Yahoo's image proxies hide where their readers are.
Located int64 `json:"located"`
// GeoIP is true when the server has a GeoIP database loaded.
GeoIP bool `json:"geoip"`
// Hours (24) and Weekdays (7), zero-filled.
Hours []ReportTimeBucket `json:"hours"`
Weekdays []ReportTimeBucket `json:"weekdays"`
// Timezone the hours and weekdays are in (the workspace's).
Timezone string `json:"timezone"`
// PrivacyOpens are left out: Apple hides the device and the place.
PrivacyOpens int64 `json:"privacyOpens"`
}
ReportBreakdown is where and when people read the campaign (M57 G-12), from campaign_dims: a message's first human engagement (a human open or a person's click) carries its mail client, system, device and place; privacy-protected and scanner opens never do.
type ReportCampaignInfo ¶
type ReportCampaignInfo struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status" enum:"draft,approval,approved,scheduled,sending,paused,sent,cancelled,failed"`
// Audience is a readable label ("All subscribers", "Weekly Digest").
Audience string `json:"audience"`
ScheduledAt *time.Time `json:"scheduledAt,omitempty"`
StartedAt *time.Time `json:"startedAt,omitempty"`
CompletedAt *time.Time `json:"completedAt,omitempty"`
// Timezone of the schedule, when one was set.
Timezone string `json:"timezone,omitempty"`
// Origin is the importer source for history pulled in by migration ("brevo").
Origin string `json:"origin,omitempty"`
// Final is true once 72 hours have passed since the send ended; until
// then opens and clicks are still coming in.
Final bool `json:"final"`
// FinalAt is when the results become final (72 h after the send ended).
FinalAt *time.Time `json:"finalAt,omitempty"`
// Notes: "A/B subject, winner B", "first send after Brevo migration".
Notes []string `json:"notes"`
}
ReportCampaignInfo is the header of the report.
type ReportCampaignRef ¶
ReportCampaignRef points to another campaign.
type ReportClickMap ¶
type ReportClickMap struct {
// HTML is the campaign's email as sent (rendered in a sandboxed frame).
HTML string `json:"html"`
// Available is false when the stored content is missing; the links
// are still listed.
Available bool `json:"available"`
Total int64 `json:"total" doc:"Human clicks on the links, each person once per link"`
BotTotal int64 `json:"botTotal" doc:"Clicks the bot filter left out"`
Links []ReportLink `json:"links"`
Threshold float64 `json:"threshold" doc:"Links under this share (percent) are grouped as Other"`
// Rows are the links on one line of the email shown as one entry; their
// links aren't in Other.
Rows []ReportLinkRow `json:"rows"`
Other *ReportLinkGroup `json:"other,omitempty"`
// Language is the language version the map shows, for a campaign sent
// in several languages.
Language string `json:"language,omitempty"`
// Variants are the A/B test's maps, one per variant (review AN-5): each
// variant's recipients' clicks (its sample and, for the winner, everyone
// who got it after the test) on the variant's email. Empty without a
// test, or when the clicks weren't kept per variant.
Variants []ReportVariantClickMap `json:"variants"`
// PerVariant: a test on content, whose variants each have their own
// email, so no one map holds everyone's clicks. The map's own HTML,
// links and totals are then variant A's (the campaign's email), as in
// Variants; read each variant's map there.
PerVariant bool `json:"perVariant"`
}
ReportClickMap is the click map: the email as sent and the clicks per link.
type ReportCodeCount ¶
type ReportCodeCount struct {
Provider string `json:"provider" doc:"Short name: SES, Postal"`
Type string `json:"type" doc:"The provider's event name: Permanent/General, HardFail"`
Code string `json:"code" doc:"SMTP reply or provider code: 550 5.1.1"`
Count int64 `json:"count"`
}
ReportCodeCount is one provider's original code within a bounce type.
func (ReportCodeCount) CodeText ¶
func (c ReportCodeCount) CodeText() string
CodeText is "SES Permanent/General 550 5.1.1".
type ReportComparison ¶
type ReportComparison struct {
Metric string `json:"metric" enum:"sent,delivered,humanOpens,privacyOpens,clicks,unsubscribes,complaints,bounces"`
// Change is the difference with the median: percent of the median for
// the count sent, percentage points for the rates.
Change float64 `json:"change"`
Unit string `json:"unit" enum:"percent,points"`
Median float64 `json:"median"`
// Tone is how the change reads: good (more deliveries, opens, clicks;
// fewer unsubscribes, complaints, bounces), bad, or neutral (the count
// sent, privacy-protected opens, no change).
Tone string `json:"tone" enum:"good,bad,neutral"`
// Trend is the metric in each of the earlier issues that have it,
// oldest first, then in this issue: the count sent, the rates in
// percent. The tile's trend line.
Trend []float64 `json:"trend"`
}
ReportComparison is one tile's change against the median of the last issues.
type ReportComparisons ¶
type ReportComparisons struct {
// Issues is how many earlier issues the medians are of (up to 6).
Issues int `json:"issues"`
Tiles []ReportComparison `json:"tiles"`
// coming in) or no_history (no earlier issue).
Unavailable string `json:"unavailable,omitempty" enum:"not_final,no_history"`
}
ReportComparisons are the tiles' comparisons.
type ReportDimRow ¶
type ReportDimRow struct {
// Key: apple_mail, ios, mobile, the ISO country code ("VN"), "VN|Hanoi"
// for a city; "other" for the folded rest.
Key string `json:"key"`
// Label is the product name ("Apple Mail", "iOS"), the English device
// word, the country code or the city's English name.
Label string `json:"label"`
// Country is a city's ISO country code.
Country string `json:"country,omitempty"`
// Places is how many cities or countries the "other" row folds.
Places int `json:"places,omitempty"`
HumanOpens int64 `json:"humanOpens"`
Clicks int64 `json:"clicks"`
}
ReportDimRow is one mail client, system, device, country or city: the people whose first human engagement came from it, and how many of them clicked. Share is its part of the dimension's human opens (percent).
type ReportEngagement ¶
type ReportEngagement struct {
// Available is false when there is no hourly data (imported history).
Available bool `json:"available"`
Points []ReportEngagementPoint `json:"points"`
// Hours of data so far (72 once final).
Hours int `json:"hours"`
// Delivered is the base the chart's percentages use.
Delivered int64 `json:"delivered"`
// HumanWithin6h is the share of the 72-hour human opens that came in
// the first 6 hours (percent).
HumanWithin6h *float64 `json:"humanWithin6h,omitempty"`
Rollout *ReportRollout `json:"rollout,omitempty"`
}
ReportEngagement is "Engagement over the first 72 hours": cumulative counts per hour, as shares of delivered on the chart.
type ReportEngagementPoint ¶
type ReportEngagementPoint struct {
Hour int `json:"hour"`
HumanOpens int64 `json:"humanOpens"`
PrivacyOpens int64 `json:"privacyOpens"`
MachineOpens int64 `json:"machineOpens"`
Clicks int64 `json:"clicks"`
}
ReportEngagementPoint is the cumulative engagement at an hour after the send.
type ReportExport ¶
ReportExport is a file to download.
type ReportFinalAlert ¶
ReportFinalAlert says whether the member asked to be emailed when the report's results are final.
type ReportGrowth ¶
type ReportGrowth struct {
// Since is when the issue went out: the counts are since then.
Since *time.Time `json:"since,omitempty"`
NewSubscribers int64 `json:"newSubscribers"`
Forwards int64 `json:"forwards"`
Referrals int64 `json:"referrals"`
WebPost int64 `json:"webPost"`
WebViews int64 `json:"webViews"`
}
ReportGrowth is "Growth & revenue from this issue" without the money, which comes from Earn.
type ReportHeadline ¶
type ReportHeadline struct {
Sent int64 `json:"sent"`
SentBy []ReportProviderCount `json:"sentBy"`
Delivered int64 `json:"delivered"`
DeliveredRate *float64 `json:"deliveredRate,omitempty"`
HumanOpens int64 `json:"humanOpens"`
HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
Measurable int64 `json:"measurable"`
HumanOpenRateMeasurable *float64 `json:"humanOpenRateMeasurable,omitempty"`
PrivacyOpens int64 `json:"privacyOpens"`
PrivacyOpenRate *float64 `json:"privacyOpenRate,omitempty"`
MachineOpens int64 `json:"machineOpens" doc:"Scanner opens, left out of every rate"`
MachineOpenRate *float64 `json:"machineOpenRate,omitempty"`
Clicks int64 `json:"clicks"`
ClickRate *float64 `json:"clickRate,omitempty"`
ClickToOpen *float64 `json:"clickToOpen,omitempty"`
// BotClicks are the clicks on the email's links the bot filter left
// out (scanners following every link, the hidden link's scanners): on
// every variant's and language version's links.
BotClicks int64 `json:"botClicks"`
Unsubscribes int64 `json:"unsubscribes"`
UnsubscribeRate *float64 `json:"unsubscribeRate,omitempty"`
Complaints int64 `json:"complaints"`
ComplaintRate *float64 `json:"complaintRate,omitempty"`
// ComplaintRateReported is complaints of the messages delivered to
// mailbox providers that report complaints; NotReportedBy names the
// ones in this send that don't ("Gmail", "iCloud", review F-2).
ComplaintRateReported *float64 `json:"complaintRateReported,omitempty"`
NotReportedBy []string `json:"notReportedBy"`
Bounces int64 `json:"bounces"`
HardBounces int64 `json:"hardBounces"`
SoftBounces int64 `json:"softBounces"`
BounceRate *float64 `json:"bounceRate,omitempty"`
// Rejected: the providers refused them, when they were handed over or
// afterwards; they were never sent.
Rejected int64 `json:"rejected"`
// Undelivered were sent and neither delivered nor bounced: deferrals
// that expired once the send is final, mail still in flight before
// that.
Undelivered int64 `json:"undelivered"`
}
ReportHeadline holds the headline tiles. Rates are percentages: delivered and bounces of sent; opens, clicks, unsubscribes and complaints of delivered; click-to-open of human opens.
Opens are in three buckets (review AN-10): people's (HumanOpens), privacy-protected (PrivacyOpens: Apple Mail opens every message on delivery, so whether anyone read it can't be measured) and scanners' (MachineOpens, left out). Measurable are the delivered recipients whose opens can be measured (all but the privacy-protected), and HumanOpenRateMeasurable is human opens of them: "41.2% of delivered · 52.8% of measurable".
type ReportIngestBacklog ¶
type ReportIngestBacklog struct {
Since time.Time `json:"since"`
Minutes int `json:"minutes"`
Providers []ReportBacklogProvider `json:"providers"`
// Current names the other providers, whose events are up to date.
Current []string `json:"current"`
}
ReportIngestBacklog says that part of the report is behind: provider events wait to be processed, so counts they feed are as of Since.
type ReportInsight ¶
type ReportInsight struct {
Kind string `json:"kind" enum:"blocked,mailbox_bounces,top_link"`
Tone string `json:"tone" enum:"bad,warn,info"`
// Title and Detail are in the reader's language.
Title string `json:"title"`
Detail string `json:"detail"`
// Action is what to do: check_delisting (Deliverability's blocklist
// checks), open_snds (Microsoft's Smart Network Data Services),
// open_postmaster (Google Postmaster Tools), show_link (the link on the
// click map); empty without one.
Action string `json:"action,omitempty" enum:"check_delisting,open_snds,open_postmaster,show_link"`
ActionLabel string `json:"actionLabel,omitempty"`
// Link is an outside address for the action (SNDS, Postmaster Tools).
Link string `json:"link,omitempty"`
// Position is the link's position on the click map (show_link).
Position *int `json:"position,omitempty"`
// Variant is the A/B variant whose map the link is on, for a test on
// content (show_link); empty otherwise.
Variant string `json:"variant,omitempty"`
// contains filtered or unexported fields
}
ReportInsight is one insight with its action.
type ReportLink ¶
type ReportLink struct {
ID string `json:"id"`
URL string `json:"url"`
Label string `json:"label"`
Position int `json:"position"`
// Clicks are every human click on the link; UniqueClicks the people who
// clicked it, which the map and its shares count.
Clicks int64 `json:"clicks"`
UniqueClicks int64 `json:"uniqueClicks"`
// BotClicks landed on this link and were left out of its clicks.
BotClicks int64 `json:"botClicks"`
Share float64 `json:"share"`
// Grouped links fall under "Other" on the map (under the threshold);
// a link of one of the map's Rows isn't grouped but drawn with its row.
Grouped bool `json:"grouped"`
// Hot marks the most-clicked links (drawn in red).
Hot bool `json:"hot"`
}
ReportLink is one tracked link of the email.
type ReportLinkGroup ¶
type ReportLinkGroup struct {
Links int `json:"links"`
Clicks int64 `json:"clicks"`
Labels []string `json:"labels" doc:"The most-clicked links in the group, for the caption"`
}
ReportLinkGroup is "Other": the links under the threshold, as one bubble.
type ReportLinkRow ¶
type ReportLinkRow struct {
// Place is where the row is: header (at the top, after a logo at
// most), footer (after every other link) or body.
Place string `json:"place" enum:"header,footer,body"`
Positions []int `json:"positions"`
Labels []string `json:"labels"`
Clicks int64 `json:"clicks" doc:"Human clicks, each person once per link"`
BotClicks int64 `json:"botClicks"`
}
ReportLinkRow is links that sit on one line of the email with only separators between them (a navigation bar: "Blog · Docs · Changelog"), each under the threshold: the map shows them as one entry and one bubble.
type ReportMailboxRow ¶
type ReportMailboxRow struct {
Key string `json:"key" enum:"gmail,outlook,yahoo,icloud,other"`
Name string `json:"name"`
ReportRates
}
ReportMailboxRow is one mailbox provider (where recipients read it).
type ReportNotSent ¶
type ReportNotSent struct {
Status string `json:"status"`
ScheduledAt *time.Time `json:"scheduledAt,omitempty"`
Timezone string `json:"timezone,omitempty"`
Readiness string `json:"readiness,omitempty" enum:"ready,warnings,blocked,"`
// LastReport is the most recent campaign with results.
LastReport *ReportCampaignRef `json:"lastReport,omitempty"`
}
ReportNotSent is the empty state of a campaign without results.
type ReportPath ¶
type ReportPath struct {
api.WorkspaceInput
CampaignID string `path:"campaignId" format:"uuid" doc:"Campaign id"`
}
ReportPath names a campaign of the workspace.
type ReportProviderColumn ¶
type ReportProviderColumn struct {
ProviderID string `json:"providerId"`
Name string `json:"name"`
Short string `json:"short"`
Adapter string `json:"adapter"`
Color string `json:"color" enum:"ses,postal,postmark,other"`
ReportRates
// Percent of the planned send routed here.
Percent float64 `json:"percent"`
// MedianDeliveryMs is the median time from handing a message over to its
// delivery event.
MedianDeliveryMs *int `json:"medianDeliveryMs,omitempty"`
// Cost in dollars; absent when unknown (history imported from another
// platform, which ReputeCast didn't pay for).
Cost *float64 `json:"cost,omitempty" doc:"Dollars"`
// WarmupDay is the warm-up day the provider was on at the send.
WarmupDay *int `json:"warmupDay,omitempty"`
// EngagedFirst is true when the warm-up sent to the most engaged contacts only.
EngagedFirst bool `json:"engagedFirst"`
// TrackedBy is whose tracking counted the opens and clicks of the
// messages sent here: ReputeCast's pixel and links, or the provider's
// own, kept in Sending providers (review AN-4).
TrackedBy string `json:"trackedBy" enum:"reputecast,provider"`
// DeliveryInferred: the provider can't report deliveries (an SMTP
// relay), so a message that hasn't bounced within 72 hours counts as
// delivered.
DeliveryInferred bool `json:"deliveryInferred"`
// Events is how the provider's delivery events arrive.
Events string `json:"events" enum:"sns,webhook,bounce_mailbox,none"`
}
ReportProviderColumn is one sending provider in the side-by-side table.
type ReportProviderCount ¶
type ReportProviderCount struct {
ProviderID string `json:"providerId"`
Short string `json:"short"`
Count int64 `json:"count"`
}
ReportProviderCount is one sending provider's part of a count ("SES 43,182").
type ReportProviderTable ¶
type ReportProviderTable struct {
Columns []ReportProviderColumn `json:"columns"`
// Split is true when more than one provider delivered the send.
Split bool `json:"split"`
}
ReportProviderTable is "Results per sending provider".
type ReportRates ¶
type ReportRates struct {
Sent int64 `json:"sent"`
Delivered int64 `json:"delivered"`
DeliveredRate *float64 `json:"deliveredRate,omitempty"`
HumanOpenRate *float64 `json:"humanOpenRate,omitempty"`
// Measurable and HumanOpenRateMeasurable: human opens of the recipients
// whose opens can be measured; PrivacyOpenRate: privacy-protected opens
// of delivered (review AN-10).
Measurable int64 `json:"measurable"`
HumanOpenRateMeasurable *float64 `json:"humanOpenRateMeasurable,omitempty"`
PrivacyOpenRate *float64 `json:"privacyOpenRate,omitempty"`
MachineOpenRate *float64 `json:"machineOpenRate,omitempty"`
ClickRate *float64 `json:"clickRate,omitempty"`
BounceRate *float64 `json:"bounceRate,omitempty"`
ComplaintRate *float64 `json:"complaintRate,omitempty"`
// ComplaintRateNA says why ComplaintRate is empty: not_reported (the
// mailbox provider doesn't report complaints to senders, review F-2).
ComplaintRateNA string `json:"complaintRateNa,omitempty" enum:"not_reported"`
UnsubscribeRate *float64 `json:"unsubscribeRate,omitempty"`
}
ReportRates are a slice of the send's results. Rates as in ReportHeadline.
type ReportRetryCampaign ¶
type ReportRetryCampaign struct {
ID string `json:"id"`
Name string `json:"name"`
Status string `json:"status"`
StartedAt *time.Time `json:"startedAt,omitempty"`
}
ReportRetryCampaign is a campaign's retry.
type ReportRollout ¶
type ReportRollout struct {
Variant string `json:"variant"`
At time.Time `json:"at"`
// Hour after the send started.
Hour float64 `json:"hour"`
}
ReportRollout is the winning A/B variant going out to everyone else.
type ReportShareIncludes ¶
type ReportShareIncludes struct {
}
ReportShareIncludes is what a read-only link shares beyond the numbers, charts and tables (review AN-16).
type ReportShareLink ¶
type ReportShareLink struct {
// URL is the public link, shown to members who may share reports.
Includes ReportShareIncludes `json:"includes"`
}
ReportShareLink is an active read-only link.
type ReportShareList ¶
type ReportShareList struct {
}
ReportShareList lists a campaign's active links.
type ReportSummarySetting ¶
type ReportSummarySetting struct {
Frequency string `json:"frequency" enum:"off,weekly,monthly" doc:"weekly: Mondays at 09:00; monthly: on the 1st at 09:00, in your time zone"`
// NextAt is when the next summary goes out.
NextAt *time.Time `json:"nextAt,omitempty" readOnly:"true" doc:"When the next summary goes out (ignored in requests)"`
}
ReportSummarySetting is the signed-in member's sending summary of the workspace.
type ReportSuppressResult ¶
type ReportSuppressResult struct {
Added int `json:"added"`
Already int `json:"already" doc:"Already on the list"`
}
ReportSuppressResult says how many bounced addresses were suppressed.
type ReportTimeBucket ¶
type ReportTimeBucket struct {
Key int `json:"key"`
HumanOpens int64 `json:"humanOpens"`
Clicks int64 `json:"clicks"`
}
ReportTimeBucket is one local hour (0-23) or ISO weekday (1-7, Monday = 1) of the workspace's time zone at the time: first human opens and first clicks in it.
type ReportUnsubscribeReason ¶
type ReportUnsubscribeReason struct {
Key string `json:"key" enum:"too_frequent,not_relevant,none,never_signed_up,spam,other"`
Label string `json:"label"`
Count int64 `json:"count"`
Tone string `json:"tone" enum:"ink,muted,bad"`
}
ReportUnsubscribeReason is one answer on the unsubscribe page.
type ReportUnsubscribes ¶
type ReportUnsubscribes struct {
Total int64 `json:"total"`
Reasons []ReportUnsubscribeReason `json:"reasons"`
// ChoseFewer chose "fewer emails" instead of leaving.
ChoseFewer int64 `json:"choseFewer"`
}
ReportUnsubscribes is "Unsubscribe reasons".
type ReportVariantClickMap ¶
type ReportVariantClickMap struct {
Key string `json:"key"`
// SameEmail: the variants share the email (a subject or send-time
// test), so the map is drawn on the campaign's email (ReportClickMap's
// HTML) and HTML is empty.
SameEmail bool `json:"sameEmail"`
HTML string `json:"html"`
Available bool `json:"available"`
Total int64 `json:"total"`
BotTotal int64 `json:"botTotal"`
Links []ReportLink `json:"links"`
Rows []ReportLinkRow `json:"rows"`
Other *ReportLinkGroup `json:"other,omitempty"`
}
ReportVariantClickMap is one A/B variant's click map.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Box *secrets.Box
URLs publicurl.Builder
Suppress Suppressor
// Limits protects the public report endpoint; nil uses defaults.
Limits *Limiter
Now func() time.Time
// Languages adds results per language; nil leaves them out.
Languages *languages.Service
// Links reads the view-online pages new subscribers came from (an
// issue's forwards); nil leaves those out.
Links *linktoken.Signer
// RetryAudience counts who an audience goes to, as Review & send counts
// them (Send Readiness): what a retry of blocked addresses would reach.
// Nil counts the blocked addresses alone.
RetryAudience func(ctx context.Context, ws *store.Workspace, audience json.RawMessage) (int64, error)
// Geo says whether countries and cities can be known; nil reads as no
// GeoIP database.
Geo GeoIP
// The sending summary by email (summary.go). Mail is read at run time:
// the system mailer is wired after the workers; nil skips the emails.
Mail func() mailer.Sender
// Jobs queues a summary's email in the transaction that claims its period.
Jobs Inserter
// Health reads the sender health the summary shows (the Overview's
// score and word); ok is false until there is one. Nil leaves it out.
Health func(ctx context.Context, ws *store.Workspace) (score int, label string, ok bool, err error)
}
func (*Service) BounceReview ¶
func (s *Service) BounceReview(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, typeKey string) (ReportBounceReview, error)
BounceReview returns what the providers said for one bounce type, without any address, so a person can decide whether to suppress them.
func (*Service) CreateShare ¶
func (s *Service) CreateShare(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, in ShareInput) (ReportShareLink, error)
CreateShare makes a read-only link to a campaign's report.
func (*Service) Export ¶
func (s *Service) Export(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, format string) (ReportExport, error)
Export writes the report as CSV (one section per table) or records a PDF export. Every export is in the audit log.
func (*Service) FinalAlert ¶
func (s *Service) FinalAlert(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (ReportFinalAlert, error)
FinalAlert reads whether the member asked.
func (*Service) QueueSummaries ¶
QueueSummaries claims every member's period that is due and queues its email in the same transaction, so overlapping ticks claim each period once. It returns how many emails it queued.
func (*Service) ReportIn ¶
func (s *Service) ReportIn(ctx context.Context, ws *store.Workspace, id uuid.UUID, lang string) (CampaignReport, error)
ReportIn is the report with the click map of one language version ("" is the source).
func (*Service) RevokeShare ¶
func (s *Service) RevokeShare(ctx context.Context, ws *store.Workspace, campaignID, shareID uuid.UUID) error
RevokeShare stops a read-only link from working.
func (*Service) SendFinalAlerts ¶
SendFinalAlerts tells everyone who asked about a report whose results became final, if they can still read it, and returns how many were told.
func (*Service) SetFinalAlert ¶
func (s *Service) SetFinalAlert(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, on bool) (ReportFinalAlert, error)
SetFinalAlert asks (on) or stops asking to be emailed when the results are final. Only a person can ask, for a campaign whose results are still coming in.
func (*Service) SetSummary ¶
func (s *Service) SetSummary(ctx context.Context, ws *store.Workspace, freq string) (ReportSummarySetting, error)
SetSummary turns the member's summary on (weekly or monthly) or off. The period the member is in counts as already behind them: the first email is the next one, not one about the week they turned it on in.
func (*Service) Shared ¶
Shared returns the report behind a read-only link, for anyone holding it. client identifies the caller for the rate limits (the client address).
func (*Service) Shares ¶
func (s *Service) Shares(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID) (ReportShareList, error)
Shares lists a campaign's active read-only links.
func (*Service) SuppressBounces ¶
func (s *Service) SuppressBounces(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, typeKey string) (ReportSuppressResult, error)
SuppressBounces adds the bounced addresses of one type that aren't on the shared suppression list yet, through the suppression service (which writes the audit entry and tells every provider).
type ShareInput ¶
type ShareInput struct {
// ExpiresInDays makes the link stop working after that many days (30
// when absent); every link expires.
IncludeEmail bool `json:"includeEmail,omitempty" doc:"Show the email as sent, in the click map"`
}
ShareInput creates a read-only link. The numbers, charts and tables are always in; the cost per provider, the warm-up state and the email itself only when chosen (review AN-16). The AI summary and the Ask box are never shared.
type SharedCampaignReport ¶
type SharedCampaignReport struct {
}
SharedCampaignReport is what a read-only link shows: the report of one campaign and the workspace it belongs to, nothing else.
type SummaryArgs ¶
type SummaryArgs struct{}
SummaryArgs claims the sending summaries that are due (periodic).
func (SummaryArgs) InsertOpts ¶
func (SummaryArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type SummarySendArgs ¶
type SummarySendArgs struct {
UserID uuid.UUID `json:"user_id"`
WorkspaceID uuid.UUID `json:"workspace_id"`
Frequency string `json:"frequency"`
From time.Time `json:"from"`
To time.Time `json:"to"`
}
SummarySendArgs emails one member the summary of one period ([From, To), in UTC).
func (SummarySendArgs) InsertOpts ¶
func (SummarySendArgs) InsertOpts() river.InsertOpts
InsertOpts implements river.JobArgsWithInsertOpts.
type SummarySendWorker ¶
type SummarySendWorker struct {
river.WorkerDefaults[SummarySendArgs]
S *Service
Log *slog.Logger
// contains filtered or unexported fields
}
SummarySendWorker runs SummarySendArgs. A provider that accepted the email just before a crash may see it once more: delivery is at least once.
func (*SummarySendWorker) Work ¶
func (w *SummarySendWorker) Work(ctx context.Context, job *river.Job[SummarySendArgs]) error
Work implements river.Worker.
type SummaryWorker ¶
type SummaryWorker struct {
river.WorkerDefaults[SummaryArgs]
S *Service
}
SummaryWorker runs SummaryArgs.
func (*SummaryWorker) Work ¶
func (w *SummaryWorker) Work(ctx context.Context, _ *river.Job[SummaryArgs]) error
Work implements river.Worker.
type Suppressor ¶
type Suppressor interface {
AddSuppressions(ctx context.Context, ws *store.Workspace, emails []string, note string, text i18n.Text) (added, already int, err error)
}
Suppressor adds addresses to the shared suppression list (the audience domain's suppression service), writing its own audit entry. The note is stored in English with its message kept, so the list reads it in each reader's language.