Referrals

Turn it on from the Referrals page or with update_referral_settings. A newsletter needs confirmation emails on, so a referral only counts once the new subscriber has proved their address, and its website on, since the links lead to its signup form. A reward is a title, the number of referrals that unlocks it (1 to 10,000) and a link or a message. Up to 10 rewards, each at a different number.

The link is the newsletter's website with the subscriber's code: https://your-slug.example.com/?ref=…. The code names the subscriber and is signed, so it can't be guessed. The visitor can read a few issues before signing up: the website keeps the code for 30 days.

Each subscriber also has a page of their own, with their link, how many people they brought in, the next reward and the rewards they unlocked, which show their link or message. It is signed, so only the subscriber has it, and it never expires. Reaching a reward sends the subscriber an email with the same, through the same sending path as the welcome email: it carries the unsubscribe link, counts toward the month's emails, and is skipped for an address on the suppression list or while the account is blocked.

Write {{referral_link}} in an issue for each subscriber's own link and {{referral_count}} for their count. In the editor, type / and pick Referral block. On the website, where readers aren't subscribers, the link goes to the signup form and the count is 0. In the RSS feed the link is the website.

<div style="margin:24px 0;padding:16px 20px;border-radius:8px;background:#f4f4f5;">
<p style="margin:0 0 8px;"><strong>Share this newsletter, get rewards.</strong> You've referred {{referral_count}} so far.</p>
<p style="margin:0;">Your link: <a href="{{referral_link}}">{{referral_link}}</a></p>
</div>

The new subscriber still joins; the referral just isn't counted. The Referrals page lists these with the reason.

• Someone already on the list, or who signs up again. Only a new subscriber can be referred, once.
• A subscriber referring themselves, by their address or an alias of it (dots and +tags at Gmail, +tags at Outlook, iCloud and others).
• Several aliases of one inbox referred by the same subscriber.
• More than two signups from one network for the same subscriber, counting the subscriber's own. A household can, a farm can't.
• Floods: 3 referrals a day from one network, 30 a day for one subscriber.
• An address that bounced, complained or is on the suppression list when it confirms, and a referrer who has left.

get_referral_settings, update_referral_settings, list_referrals and get_referral_leaderboard work from the REST API and MCP. A signup form of your own passes the ref of the address the visitor arrived by as referral to add_contact.