Documentation
¶
Overview ¶
Package tracking serves the open pixel and the click redirect that go in every tracked email, and records opens and clicks honestly: human opens separated from machine opens (Apple Mail Privacy Protection, image proxy prefetches, security scanners) and bot clicks kept out of the counts.
GET /t/o/{token} 1×1 transparent GIF, never cached; records the open
GET /t/c/{token} 302 to the email's link; records the click
Tokens are signed (internal/linktoken) and name the message, the contact and, for clicks, the link's position in the campaign's links: the redirect only ever goes to a link of that message (no open redirect). Writes are group-committed in the background, so the pixel and the redirect stay fast under load. The unsubscribe page and RFC 8058 one-click POST live with the public pages.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClientName ¶
ClientName turns a user agent into "Chrome on macOS", "Outlook on Windows", "Apple Mail on iOS".
Types ¶
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Links *linktoken.Signer
Log *slog.Logger
Automations *automations.Service
Now func() time.Time
// contains filtered or unexported fields
}
Service records opens and clicks.
func (*Service) RecordEngagement ¶
RecordEngagement implements sending.Recorder: it classifies and records a batch of opens and clicks in one transaction.
type Signal ¶
type Signal struct {
UserAgent string
IP netip.Addr
// Method is the HTTP method; scanners often probe with HEAD.
Method string
// SinceSend is how long after the message was handed to the provider
// the request came (negative when unknown).
SinceSend time.Duration
}
Signal is what a tracking request tells us about who made it.
type Verdict ¶
type Verdict struct {
// Machine is true for opens and clicks no person made: privacy proxies
// prefetching images, security scanners following links.
Machine bool
// Reason explains a machine verdict in the live feed's words
// ("Apple Mail Privacy Protection prefetch").
Reason string
// Client is the mail client or browser, for human events
// ("Chrome on macOS").
Client string
}
Verdict classifies an open or a click.
func ClassifyClick ¶
ClassifyClick decides whether a click was a person. Bot clicks still get redirected; they are logged but never counted as clicks.
Bot clicks: HEAD requests, empty or scanner user agents, scanner networks within two minutes of sending, clicks within ten seconds of sending, and bursts (burst is true when the same message already clicked several different links within the last few seconds, as scanners that follow every link do).
func ClassifyOpen ¶
ClassifyOpen decides whether an open pixel fetch was a person.
Machine opens, in order:
- HEAD requests and empty user agents.
- Apple Mail Privacy Protection: requests from Apple's network (17.0.0.0/8) or with the bare "Mozilla/5.0" user agent its proxies send. They fetch every image on delivery whether or not anyone reads.
- Gmail's GoogleImageProxy and Yahoo's YahooMailProxy within 30 s of sending (caching on arrival); later fetches are people opening in Gmail or Yahoo Mail and count as human.
- Security scanners and HTTP libraries (user agent), and scanner networks within two minutes of sending.
- Anything within two seconds of sending.