flarelytics / docs / email-reports

Email Reports

Weekly analytics digests delivered to your inbox. The email-reports worker runs on a cron schedule and queries your analytics worker to build and send a summary email.

Overview

Each weekly report includes:

  • KPI cards — pageviews, unique visitors, and custom event count with week-over-week change
  • Anomaly alerts — flagged automatically when traffic changes by more than 30%
  • Top 5 pages by pageviews
  • Top 3 referrer sources
  • Top 3 countries
  • Bot traffic summary — total blocked requests and top bot user-agents

The email-reports package is a separate Cloudflare Worker. It does not share state with the main analytics worker — it only calls the analytics worker's /query API to fetch data.

Setup

Step 1

Copy the example config:

cp packages/email-reports/wrangler.toml.example packages/email-reports/wrangler.toml
Step 2

Edit packages/email-reports/wrangler.toml with your values:

wrangler.toml
name = "my-site-email-reports"
 
[vars]
ANALYTICS_WORKER_URL = "https://my-site-analytics.workers.dev"
EMAIL_API_URL = "https://api.euromail.eu"
EMAIL_FROM = "[email protected]"
SITE_NAME = "My Site"
SITE_URL = "https://mysite.com"
 
[triggers]
crons = ["0 9 * * 1"] # Monday at 9am UTC
 
[[kv_namespaces]]
binding = "REPORT_RECIPIENTS"
id = "your-kv-namespace-id"

Environment variables:

  • ANALYTICS_WORKER_URL — base URL of your main analytics worker
  • ANALYTICS_API_KEY — the QUERY_API_KEY secret from your main worker
  • EMAIL_API_URL — email service base URL (Euromail, Resend, SendGrid)
  • EMAIL_API_KEY — email service API key
  • EMAIL_FROM — sender address
  • SITE_NAME — displayed in the report header
  • SITE_URL — used for page links in the report
Step 3

Create the KV namespace for recipients and copy the ID into wrangler.toml:

npx wrangler kv namespace create REPORT_RECIPIENTS
Step 4

Set the secrets that should not go in wrangler.toml:

# API key from your main analytics worker
npx wrangler secret put ANALYTICS_API_KEY
 
# Email service API key
npx wrangler secret put EMAIL_API_KEY
 
# Random string — protects /recipients and /test endpoints
npx wrangler secret put ADMIN_API_KEY
Step 5

Deploy:

cd packages/email-reports
npx wrangler deploy
Cron schedule
0 9 * * 1 fires every Monday at 9am UTC. Adjust the cron expression in wrangler.toml to change the schedule. Cloudflare cron triggers require a paid Workers plan.

Managing recipients

All recipient endpoints require X-API-Key: <ADMIN_API_KEY>.

Add a recipient

curl
curl -X POST https://my-site-email-reports.workers.dev/recipients \
-H "X-API-Key: your-admin-api-key" \
-H "Content-Type: application/json" \
-d '{\"email\":\"[email protected]\"}'

Remove a recipient

curl
curl -X DELETE https://my-site-email-reports.workers.dev/recipients \
-H "X-API-Key: your-admin-api-key" \
-H "Content-Type: application/json" \
-d '{\"email\":\"[email protected]\"}'

List all recipients

curl
curl https://my-site-email-reports.workers.dev/recipients \
-H "X-API-Key: your-admin-api-key"

Testing

Send a test report to any address without waiting for the cron to fire:

curl
curl -X POST https://my-site-email-reports.workers.dev/test \
-H "X-API-Key: your-admin-api-key" \
-H "Content-Type: application/json" \
-d '{\"email\":\"[email protected]\"}'

The response includes the generated subject line and whether the send succeeded.

Report contents

Each digest covers the previous 7 days and compares it to the 7 days before that.

  • KPI cards — pageviews, unique visitors, and custom event count, each with a colour-coded week-over-week percentage change
  • Anomaly alerts — shown when pageview count changes by more than 30% compared to the prior week
  • Top 5 pages — paths ranked by pageview count
  • Top 3 referrers — referrer hostnames ranked by visit count
  • Top 3 countries — country codes ranked by pageview count
  • Bot traffic — total blocked requests and up to 5 top bot user-agents (only shown when bot hits are present)

Was this page helpful?

← Events & Schema
Edit this page on GitHub