What's this whole referral thing about, anyway?

Okay, so, subscriber referrals. You might be familiar with the whole "MorningBrew viral loop" thing, and are interested in building that; you may just be curious about who your most vocal subscribers are and you want to reward them at an ad-hoc basis. Buttondown's main goal with this functionality is to provide you with the primitives to build a referral system without being too opinionated about what that referral system is.

What this means is, at a high level:

1. By default, every subscriber gets a referral code! It's a six-digit alphabetical string, like feiojk or hamdes.
2. Buttondown exposes sign-up links for each referral code. These sign-up links are like your default subscribe pages & archive pages, but with a small affordance letting folks know that they're being referred.
3. If someone signs up to your newsletter based on one of these sign-up links, a "referral" is created. This referral is exposed in all the usual places: exports, the API, and the analytics pages.

Generating referral links

I'll skip to the most important part: "how do I give people the link they care about"?

This markdown snippet sums it up:

https://buttondown.email/<yourusername>/referral/{{ subscriber.referral_code }}

Or, if you're using a custom domain:

https://<yourcustomdomain>/referral/{{ subscriber.referral_code }}

That snippet represents a long-lasting, unique referral link for each subscriber you have. This means that you can put language in your email (or footer, or header) along the lines of:

Loved this edition of the newsletter? If you get five people to sign up
from [this link](https://buttondown.email/<yourusername>/referral/{{ subscriber.referral_code }}),
you'll get a free tote bag!

In a bit more depth: every subscriber has a referral_code that is retrievable using Buttondown's template language. When this is passed to the above URL, your main subscribe page is displayed but with a notice that mentions that the given subscriber is referring them. If someone signs up to your newsletter from that link, it'll be marked that they were referred!

Tracking referrals

You can view the referrals for your newsletter in three places:

1. You can view the specific referrals made by a given subscriber by viewing their Notes. This modal contains a list of all subscribers who have been referred by that subscriber, alongside their given status & subscription date.
2. You can view an aggregate list of all referrals made by all subscribers to your newsletter by heading over to your Analytics page. The topline modal has a total aggregation of referrals for the given date range you've selected, grouped by subscriber.
3. You can export all of your data, which contains an itemized list of all subscriber referrals made by all subscribers to your newsletter.

FAQs

Why don't the links at the bottom of my emails automatically act as referrals?

This is a great question and the boring answer is that I want to be careful about rolling out this functionality. In due time, this will be how it works.

Can subscribers change their own referral code?

Not at the moment, though this too is planned functionality.

The long-term vision for this feature is to also allow subscribers to have a lightweight interface for tracking their own referrals.

I have an idea or a complaint about how referrals work.

Please let us know on the tracking ticket for the feature!