metadata__referral_source
Incoming subscribe URL ?ref= token
Never displayed raw; used only to attribute a confirmed subscriber to an inviter.
Leaderboard plan
Public gamification stays private until attribution is real.
This page documents the leaderboard shape for MY-2571 wiring. It publishes no private emails and shows no live rankings until confirmed Buttondown subscriber counts are available.
Buttondown metadata
Fields to verify before scoring
metadata__reader_token
Browser-local share token generated on /share/
Can be mapped to an approved display name after opt-in.
metadata__signup_market
Static hidden field
Market filter for multi-newsletter dashboards.
tag
Buttondown embedded form tag website-subscribe
Operational filter only; never shown to readers.
Public table shape
Safe fields only
| Public field | Rule |
|---|---|
| Rank | Sort by confirmed referral count after fraud checks. |
| Display name | Initials, first name plus area, or opted-in community name only. |
| Area | Reader-selected broad St Albans or Harpenden area; no street-level data. |
| Confirmed referrals | Count confirmed Buttondown subscribers with matching referral_source, excluding reversals and abuse. |
| Reward tier | Show reward label only; prize fulfilment remains manually approved. |
Static artifact
Machine-readable placeholder
Open leaderboard.json for the future Buttondown exporter contract. It is placeholder-only until confirmed subscriber attribution is wired, deduplicated and reviewed.
Webhook gates
What must be true before rankings move
Rule
Buttondown subscriber.created or equivalent event is received with metadata fields intact.
Rule
Confirmation state is checked before a referral increments public totals.
Rule
Self-referrals and duplicate email aliases are excluded before scoring.
Rule
A private attribution table exists separately from the public leaderboard view.
Rule
Leaderboard cache can be rebuilt without exposing raw subscriber records.
Rule
Manual kill switch hides public rankings if abuse, privacy or sponsor-risk flags appear.
Launch sequence
Private ledger before public leaderboard
Rule
Keep /share/ and /subscribe/ static referral capture in place.
Rule
Verify Buttondown stores referral_source, reader_token and signup_market from embedded form submissions.
Rule
Backfill a private referral ledger from confirmed subscribers only.
Rule
Generate a redacted leaderboard JSON containing publicColumns only.
Rule
Review reward wording and sponsor-backed prize terms manually.
Rule
Publish public rankings only after the editor approves the live leaderboard.
Fraud checks
Before any prize or sponsor-backed draw
Rule
Block duplicate self-referrals once signup webhook exists.
Rule
Review same-IP clusters before publishing leaderboard.
Rule
Exclude disposable email domains from prize eligibility.
Rule
Only count confirmed Buttondown subscribers.
Rule
Do not publish private emails on the leaderboard.
Publication gates
What must pass before rankings go live
Rule
Export or webhook source must include only confirmed Buttondown subscribers.
Rule
Referral counts must be deduplicated by subscriber email and reader token before any ranking is shown.
Rule
Public display names must use initials, explicit opt-in names or area labels; never raw emails.
Rule
Prize eligibility must be reviewed manually before any sponsor-backed draw is announced.
Rule
Leaderboard JSON must be generated as a static artifact; no private subscriber API response is exposed client-side.
Safety gates: Do not publish live rankings, prize winners, private emails or sponsor-backed rewards until Buttondown attribution is verified and the editor approves the public launch.