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 Winchester and Hampshire cathedral towns 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. |
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.
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.