API reference

Email reports

Scheduled digest emails with a site's stats, one subscription per recipient. Reports are generated and mailed by Totallytics; recipients need no account.

Base URL: https://analytics.bitgate.dev. Download OpenAPI or read this page as Markdown.

Access

All /api/sites/{hostname}/reports endpoints require the site owner Firebase ID bearer token, even for public sites. The unsubscribe endpoints are public: the token in the link is the capability.

Method	Route	Result
GET	`/api/sites/{hostname}/reports`	List subscriptions
POST	`/api/sites/{hostname}/reports`	Add a recipient (`201`)
PATCH	`/api/sites/{hostname}/reports/{id}`	Update frequency, schedule, sections
DELETE	`/api/sites/{hostname}/reports/{id}`	Remove a recipient
POST	`/api/sites/{hostname}/reports/{id}/test`	Queue a test email for the current window
GET	`/api/sites/{hostname}/reports/preview`	Render the email as HTML
GET	`/api/reports/unsubscribe/{token}`	Confirmation page (HTML)
POST	`/api/reports/unsubscribe/{token}`	One-click unsubscribe (HTML)

Cadence and windows

Frequency	Sends	Covers
`daily`	every day	yesterday (local)
`weekly`	Mondays	previous Monday to Sunday
`monthly`	the 1st of the month	previous calendar month

send_hour is a local wall-clock hour (0-23) in the subscription's IANA timezone; daylight-saving changes follow the clock, not a fixed UTC offset. Every report covers the last fully elapsed period, so a weekly report mailed Monday 09:00 Europe/Amsterdam always covers the Monday-Sunday that just ended in that timezone.

Sections

Key	Default	Contents
`overview`	always on	Totals, change vs previous period, chart, live count
`pages`	on	Top 5 pages with change vs previous period
`referrers`	on	Top 5 referrers with change
`countries`	off	Top 5 countries with change
`events`	off	Top 5 events with change
`alerts`	on	Spike/dip callout for abnormal days

The alert section flags a day when its pageviews land more than 2.5 standard deviations and at least 50% away from the trailing 28-day mean, and names the top referrers driving a spike. Sites need about two weeks of history before alerts can trigger.

Create a subscription

POST /api/sites/{hostname}/reports accepts email, frequency, and optional timezone (default UTC), send_hour (default 9) and sections. One subscription per site, email and frequency; duplicates return 409. At most 25 recipients per site.

curl -X POST "$TT_HOST/api/sites/$TT_HOSTNAME/reports" \
  -H "Authorization: Bearer $TT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"teammate@company.com","frequency":"weekly","timezone":"Europe/Amsterdam","send_hour":9}'

PATCH accepts any subset of frequency, timezone, send_hour, enabled, sections. Setting enabled to false pauses without deleting.

POST .../test queues a real email for the current last-full-period window and returns 202 with the window it used. Test sends never consume or block the scheduled window.

GET .../preview?frequency=weekly&tz=Europe/Amsterdam&sections=pages,referrers,alerts renders the email HTML inline; omit sections to see everything on.

Delivery and unsubscribe

Mail is sent from reports@totallytics.com over a Postmark broadcast stream with List-Unsubscribe and RFC 8058 one-click headers. Unsubscribing sets enabled to false and keeps history; re-enable from the site's settings. A permanent failure (invalid address or previously hard-bounced recipient) disables the subscription immediately; transient failures retry three times, then the send is marked failed and fail_count rises. Subscriptions with five consecutive failures stop being scheduled until re-enabled.