tracking

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

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

func ClientName(ua string) string

ClientName turns a user agent into "Chrome on macOS", "Outlook on Windows", "Apple Mail on iOS".

func DiagnosticIn

func DiagnosticIn(l i18n.Lang, s string) string

DiagnosticIn writes a stored verdict ("Apple Mail Privacy Protection prefetch", "Chrome on macOS") in a reader's language. Text tracking didn't write, such as a provider's bounce message, is returned as it is.

Types

type ClickTarget

type ClickTarget struct {
	WorkspaceID uuid.UUID
	MessageID   uuid.UUID
	ContactID   uuid.UUID
	URL         string
	At          time.Time
}

ClickTarget is a click about to be redirected, as Decorate sees it.

type ClickedLink struct {
	WorkspaceID  uuid.UUID
	MessageID    uuid.UUID
	ContactID    *uuid.UUID
	CampaignID   *uuid.UUID
	AutomationID *uuid.UUID
	Target       string
	At           time.Time
}

ClickedLink is a click about to be redirected: the message's email and the destination.

type HumanClick

type HumanClick struct {
	WorkspaceID uuid.UUID
	MessageID   uuid.UUID
	CampaignID  *uuid.UUID
	ContactID   *uuid.UUID
	Stream      string
	// URL is the link as the email has it (it may hold Liquid).
	URL string
	At  time.Time
}

HumanClick is a person's click, as Clicked hears of it.

type LinkDecorator

type LinkDecorator interface {
	Decorate(ctx context.Context, c ClickedLink) string
}

LinkDecorator may rewrite a click's destination before the redirect. It runs on every click, so it must answer fast (cache what it reads).

type PlacementLinks interface {
	TrackedLink(ctx context.Context, copyID uuid.UUID, position int) (string, bool)
}

PlacementLinks resolves a placement test copy's tracked links.

type Service

type Service struct {
	Pool        *pgxpool.Pool
	Q           *store.Queries
	Links       *linktoken.Signer
	Log         *slog.Logger
	Automations *automations.Service
	// Transactional resolves the tracked links of transactional messages
	// and fires their message.opened and message.clicked webhook events.
	Transactional TransactionalTracking
	// Placement resolves the links of placement test copies, whose opens
	// and clicks are never counted (internal/placement).
	Placement PlacementLinks
	// Decorators may add parameters to a click's destination: links to a
	// connected store get UTM parameters and the click token
	// (internal/commerce).
	Decorators []LinkDecorator
	// MessageVars are an automation email's own link variables, from what
	// its trigger passed ("checkout_url": the store's recovery link).
	MessageVars func(ctx context.Context, msgCtx map[string]string) map[string]string
	Now         func() time.Time
	// Clicked, when set, hears of each person's click (bot clicks never
	// reach it) in the transaction that records it: Earn counts clicks on
	// upgrade links per campaign.
	Clicked func(ctx context.Context, q *store.Queries, c HumanClick) error
	// Decorate, when set, may add to a click's destination before the
	// redirect (Earn's click token on the publisher's own domains); "" keeps
	// the destination as it is. It runs after Decorators, and adds nothing
	// to a link that already carries rc_click.
	Decorate func(ctx context.Context, c ClickTarget) string
	// Recipients add the per-reader variables of blocks (Grow's
	// referral.* links) to personalized links; nil adds none.
	Recipients func() []liquid.RecipientData
	// contains filtered or unexported fields
}

Service records opens and clicks.

func (*Service) RecordEngagement

func (s *Service) RecordEngagement(ctx context.Context, evs []sending.Engagement) error

RecordEngagement implements sending.Recorder: it classifies and records a batch of opens and clicks in one transaction.

func (*Service) Routes

func (s *Service) Routes(r chi.Router)

Routes mounts the tracking endpoints.

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 TransactionalTracking

type TransactionalTracking interface {
	TrackedLink(ctx context.Context, q *store.Queries, messageID uuid.UUID, position int) (string, bool)
	Engagement(ctx context.Context, tx pgx.Tx, messageID uuid.UUID, click bool, at time.Time) error
}

TransactionalTracking is what the tracking endpoints need from transactional email: each message keeps its own tracked links (their targets differ per recipient), and engagement fires webhooks.

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

func ClassifyClick(s Signal, burst bool) Verdict

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

func ClassifyOpen(s Signal) Verdict

ClassifyOpen decides whether an open pixel fetch was a person.

Machine opens, in order:

  1. HEAD requests and empty user agents.
  2. 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.
  3. 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.
  4. Security scanners and HTTP libraries (user agent), and scanner networks within two minutes of sending.
  5. Anything within two seconds of sending.

Jump to

Keyboard shortcuts

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