Documentation
¶
Overview ¶
Package emailstats keeps the email statistics: the facts the Email Overview's figures are counted from, the scheduled walk that fills them (docs/superpowers/specs/2026-11-08-site-and-email-statistics-design.md, section 5, D10 and D18), and the read that counts them for a caller (section 7, statistics.go). It is the `emailStats` plug-in, a component: it reads this cluster's own campaign rows and writes this cluster's own tables, and calls nobody's API.
Why a side table ¶
The figures are counts grouped by day and by organization, campaign, rule, journey and audience. The query language counts in the database but cannot group counts by time; a daily trend across an organization's campaigns would cost hundreds of count queries per page load. Counters bumped by each writer were the other choice, and they drift: a delivery's outcome is written on three different paths (the drain worker, the single-send path, the provider feedback ingester), any of which can run on any node. So the rollup records, in email_stat_fact, one row per countable fact, and the read groups those rows with ordinary SQL.
Why through the engine ¶
The campaign rows are graph rows, and hand-written SQL over the graph is the measured hazard the design rules out: the latest-version collapse, the id spellings and the row admission live in the engine. The walk asks seven @serverOnly queries under the rollup's maintenance principal and internal origin, and only this package's own tables are written with SQL (rollup.go). Each of the seven projects only what the facts read -- no address, no address digest, no owner; the one reference to a recipient is the id a consent event is judged and counted under -- because the walk reads every organization's recipients and a figure needs none of the rest (TestTheWalkReadsNoAddressAndNothingTheFactsDoNotUse).
One fact per source record and kind ¶
A fact is keyed by the record it is about and its kind -- a delivery's send, an engagement event's open, a consent event's unsubscribe -- and every write is ON CONFLICT DO NOTHING. That one rule is what makes a rerun, the five-minute overlap, a new version of a delivery and two replicas' runs all count each fact once (facts.go).
Why the five-minute overlap ¶
Each source is walked from a watermark, the newest row.createdAt a run has written past, less five minutes. A row's time is stamped by the clock of the node that wrote it and the row commits after that, so a row can arrive with a time before a watermark another run already moved past; reading five minutes behind picks it up, and reading a row twice costs nothing. The watermark never passes the clock of the run that writes it, so one row stamped ahead cannot hide the rows after it; that clock only caps it, for a row dated past it, and never moves it past a row the walk read, so a cron leader whose clock runs fast cannot shrink the overlap for rows a true clock stamps (rollup.go, "Never past the clock"). How far the read counts is a second instant beside it, how far the source has been walked: the newest row too, or, once a walk has read its last page, the clock it asked that page by, rows or none. A figure whose sources' walks have not reached a day is null there, never zero (statistics.go).
Attribution (D18) ¶
A rule's send carries its rule; a journey's send names its enrollment in its request id, and the enrollment names the journey, which the send counts under only when the enrollment is in the send's own organization -- a request id is a string the sender chose (rollup.go, attribute); a subscribe or an unsubscribe names a recipient, whose audience it is counted under. The two lookups run once per page through the engine, in batches. Opens and clicks exist for campaign mail only, because only campaign mail is tracked.
Test runs are not statistics ¶
A test run is a campaign of its own, sent to the organization's testing audience. Nothing of it makes a fact -- its sends, opens and clicks, and the consent events it gave rise to -- and neither do the consent events of the testing audience's people, who are the organization's own staff. Two more lookups a page, made after the page is read, say which of its campaigns are test runs and which of its audiences are testing audiences (rollup.go, "Test runs are not statistics").
The read, narrowed to the caller's organizations (D11) ¶
builtin emailStatistics groups the facts with ordinary SQL over this package's own table, for the organizations the caller's grant reaches (MemQLEngine.ResolveAccessGrant, the row gate's own resolution). An organization the caller does not reach is dropped, not refused, so naming another client's organization answers every figure null; a figure nothing measured is null, never zero; and the open and click rates are of the campaign mail sent in a period, by send-day cohort (statistics.go).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AudienceFigures ¶
AudienceFigures is one audience's subscription changes in the period; Net is Subscribes - Unsubscribes.
type AutomationFigures ¶
AutomationFigures is one rule's or journey's mail in the period; Kind is automationRule or automationJourney.
type CampaignFigures ¶
type CampaignFigures struct {
ID string
Sent, UniqueOpens, UniqueClicks int64
OpenRate, ClickRate *float64
}
CampaignFigures is one campaign's sends in the period, or one organization's (the Accounts rows, ID the organization). UniqueOpens and UniqueClicks are of those sends' messages, on any day; OpenRate and ClickRate are them over the campaign sends, nil for an organization that sent no campaign mail.
type EmailPoint ¶
type EmailPoint struct {
At time.Time
// The bucket's figures, each counted as EmailTotals counts it.
Sent, UniqueOpens, UniqueClicks, Unsubscribes, Subscribes, Bounces, Complaints, Failed, Suppressed *int64
// OpenRate and ClickRate are of the campaign mail sent in the bucket,
// opened or clicked on any day.
OpenRate, ClickRate *float64
}
EmailPoint is one bucket of a series, starting At.
type EmailStatistics ¶
type EmailStatistics struct {
Period statsperiod.Period
// Bucket is statsperiod's: day or month.
Bucket string
// Start and End are the period; PrevStart and PrevEnd the one before it,
// zero when HasPrevious is false.
Start, End, PrevStart, PrevEnd time.Time
HasPrevious bool
// MeasuredSince is the cluster's first recorded day, the earliest day
// with a fact of any organization's, as the plan has it: a date, never a
// figure, which a member may be shown though it came from another
// organization's mail. nil when the cluster has no fact, or when the
// caller reaches no organization, who is never shown it.
MeasuredSince *time.Time
Totals EmailTotals
// Previous is the previous period's figures, every one nil without one.
Previous EmailTotals
// Series has one point per bucket, oldest first, and PreviousSeries the
// previous period's, aligned by offset; nil without a previous period.
Series, PreviousSeries []EmailPoint
// Campaigns are the campaignsKept campaigns with sends in the period, most
// unique opens first, then most unique clicks, most sent, and by id.
Campaigns []CampaignFigures
// Automations are the rules and journeys with a send, a failure or a
// suppression in the period, most sent first.
Automations []AutomationFigures
// Audiences are the audiences with subscription changes in the period,
// the largest net change first.
Audiences []AudienceFigures
// Accounts are the organizations with sends in the period, most sent
// first, listed only when the read covers more than one organization.
Accounts []CampaignFigures
}
EmailStatistics is one read's answer.
func (EmailStatistics) Payload ¶
func (s EmailStatistics) Payload() map[string]any
Payload is the answer as the node carries it, which the OS parses (parseEmailStatistics): lowerCamel keys, instants in RFC3339, measuredSince as YYYY-MM-DD, and every figure nothing measured PRESENT AND NULL, so a client can tell "not measured" from a key it does not know -- the website read's payload (component/sitetraffic, Statistics.Payload). Without a previous period, previous, previousSeries, prevStart and prevEnd are null.
type EmailTotals ¶
type EmailTotals struct {
Sent, Delivered, Undelivered, Failed, Skipped, Suppressed *int64
// Opens and Clicks are the events in the range; UniqueOpens and
// UniqueClicks the messages first opened or clicked in it, whenever they
// were sent.
Opens, Clicks, UniqueOpens, UniqueClicks *int64
Unsubscribes, Bounces, Complaints, Subscribes *int64
// OpenRate and ClickRate are of the campaign mail sent in the range, by
// cohort; nil when none was sent.
OpenRate, ClickRate *float64
}
EmailTotals are a range's figures; nil is "not measured".
type Engine ¶
Engine is the narrow engine surface the rollup needs: the seam every Go component in this tree uses to ask a named query.
type Fact ¶
type Fact struct {
Kind, SourceID, AccountID, CampaignID, RuleID, JourneyID, AudienceID string
// Day is the fact's UTC day, at midnight.
Day time.Time
}
Fact is one countable thing about one source record, as email_stat_fact stores it.
type GrantResolver ¶
type GrantResolver interface {
ResolveAccessGrant(ctx context.Context) memql.AccessGrant
OrganizationCapable(ctx context.Context, account, verb, resource string) bool
OrganizationReadContext(ctx context.Context) (context.Context, *auth.ReadFailures)
}
GrantResolver supplies membership, capability decisions and fresh failure- tracked authorization evidence. Membership alone is not permission to read email figures. The engine implements all three; an incomplete handle narrows every read to nothing.
type Integration ¶
type Integration struct {
// contains filtered or unexported fields
}
Integration exposes the rollup and the statistics read.
func NewIntegration ¶
NewIntegration wires the handles. The db getter is resolved at call time, not at construction: a node's database handle is not necessarily up when plug-ins are materialized.
The statistics read's grant resolver is ASSERTED on the engine handle, not required of it: the rollup needs only Execute, and the engine every node passes implements the full GrantResolver. A handle missing any part leaves grants nil, which narrows every read to nothing rather than failing the rollup's wiring or treating membership alone as permission.
func (*Integration) Capabilities ¶
func (i *Integration) Capabilities() []memql.IntegrationCapability
Capabilities implements memql.IntegrationProvider.
func (*Integration) IntegrationName ¶
func (i *Integration) IntegrationName() string
IntegrationName implements memql.IntegrationProvider.
type RollupReport ¶
type RollupReport struct {
// Rows is how many rows each source's walk read, the overlap's included.
Rows map[string]int `json:"rows"`
// Facts is how many facts the run newly recorded; a fact already there
// is not counted again.
Facts int `json:"facts"`
// Deleted is how many facts retention removed.
Deleted int64 `json:"deleted"`
// Behind names the sources whose walk stopped at its page bound with
// rows still to read: a backfill under way, which the next run continues.
Behind []string `json:"behind,omitempty"`
}
RollupReport says what one run did.