reports

package
v1.6.0 Latest Latest
Warning

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

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

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

View Source
const (
	DefaultShareDays = 30
	MaxShareDays     = 90
)

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).

View Source
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.

View Source
const CompareIssues = 6

CompareIssues is how many earlier issues the medians are of.

View Source
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.

View Source
const HotShare = 20.0

HotShare is the share of clicks (percent) from which a link's bubble is red.

View Source
const LinkThreshold = 5.0

LinkThreshold is the share of clicks (percent) under which a link is grouped as "Other" on the click map.

View Source
const MaxActiveLinks = 10

MaxActiveLinks caps the read-only links a campaign can have at once.

View Source
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.

View Source
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.

View Source
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

func Register

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

Register adds the report operations.

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.

func (FinalAlertsArgs) Kind

func (FinalAlertsArgs) Kind() string

Kind implements river.JobArgs.

type FinalAlertsWorker

type FinalAlertsWorker struct {
	river.WorkerDefaults[FinalAlertsArgs]
	S *Service
}

FinalAlertsWorker runs FinalAlertsArgs.

func (*FinalAlertsWorker) Work

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.

func (*Limiter) Allow

func (l *Limiter) Allow(key string, now time.Time) bool

Allow counts a request from key and reports whether it may proceed: it is refused over the request cap, or when the address already looked up too many unknown links.

func (*Limiter) Miss

func (l *Limiter) Miss(key string, now time.Time)

Miss records a lookup of an unknown, revoked or expired link.

type RebuildArgs

type RebuildArgs struct {
	CampaignID uuid.UUID `json:"campaign_id"`
}

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.

func (RebuildArgs) Kind

func (RebuildArgs) Kind() string

Kind implements river.JobArgs.

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.

func (RebuildSweepArgs) Kind

func (RebuildSweepArgs) Kind() string

Kind implements river.JobArgs.

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

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

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"`
	// Unavailable says why no retry can be made: is_retry (this campaign is
	// 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

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

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"`
	// Unavailable says why nothing is compared: not_final (results still
	// 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"`
	Share      float64 `json:"share"`
}

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

type ReportExport struct {
	Filename string
	Body     []byte
}

ReportExport is a file to download.

type ReportFinalAlert

type ReportFinalAlert struct {
	On      bool       `json:"on"`
	FinalAt *time.Time `json:"finalAt,omitempty"`
}

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 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 of the map's human clicks (people per link), percent.
	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 {
	Share  float64  `json:"share"`
	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"`
	Share     float64  `json:"share"`
}

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 {
	Cost   bool `json:"cost" doc:"The cost per sending provider"`
	Warmup bool `json:"warmup" doc:"The warm-up day of each sending provider"`
	Email  bool `json:"email" doc:"The email as sent, in the click map"`
}

ReportShareIncludes is what a read-only link shares beyond the numbers, charts and tables (review AN-16).

type ReportShareLink struct {
	ID string `json:"id"`
	// URL is the public link, shown to members who may share reports.
	URL           string     `json:"url"`
	CreatedAt     time.Time  `json:"createdAt"`
	CreatedByName string     `json:"createdByName"`
	ExpiresAt     *time.Time `json:"expiresAt,omitempty"`
	Views         int64      `json:"views"`
	LastViewedAt  *time.Time `json:"lastViewedAt,omitempty"`
	// Includes is what the link shares beyond the numbers.
	Includes ReportShareIncludes `json:"includes"`
}

ReportShareLink is an active read-only link.

type ReportShareList

type ReportShareList struct {
	Items []ReportShareLink `json:"items"`
}

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"`
	Share float64 `json:"share" doc:"Share of unsubscribes, percent"`
	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

func (s *Service) QueueSummaries(ctx context.Context) (int, error)

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) Report

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

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

func (s *Service) SendFinalAlerts(ctx context.Context) (int, error)

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

func (s *Service) Shared(ctx context.Context, token, client string) (SharedCampaignReport, error)

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) Summary

Summary reads the signed-in member's sending summary.

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.
	ExpiresInDays int  `json:"expiresInDays,omitempty" minimum:"1" maximum:"90" doc:"30 when absent"`
	IncludeCost   bool `json:"includeCost,omitempty" doc:"Show the cost per sending provider"`
	IncludeWarmup bool `json:"includeWarmup,omitempty" doc:"Show the warm-up day of each sending provider"`
	// IncludeEmail shows the email as sent in the click map.
	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 {
	Workspace string              `json:"workspace"`
	ExpiresAt *time.Time          `json:"expiresAt,omitempty"`
	Includes  ReportShareIncludes `json:"includes"`
	Report    CampaignReport      `json:"report"`
}

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.

func (SummaryArgs) Kind

func (SummaryArgs) Kind() string

Kind implements river.JobArgs.

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.

func (SummarySendArgs) Kind

func (SummarySendArgs) Kind() string

Kind implements river.JobArgs.

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

Work implements river.Worker.

type SummaryWorker

type SummaryWorker struct {
	river.WorkerDefaults[SummaryArgs]
	S *Service
}

SummaryWorker runs SummaryArgs.

func (*SummaryWorker) Work

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.

Jump to

Keyboard shortcuts

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