Buttondown logo

Subscribers referring other subscribers

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.

First things first: before you generate a referral link you need to make sure this feature is enabled on your newsletter. To do this, go to Settings → General, and toggle on "Referrals".

Now the important part: "How do I give people the link they care about"?

This markdown snippet sums it up:

https://buttondown.com/<yourusername>/?referral_code={{ subscriber.referral_code }}

Or, if you're using a custom domain:

https://<yourcustomdomain>/?referral_code={{ 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.com/<yourusername>/?referral_code={{ 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!

warning

Not seeing a referral code populate? Make sure this is enabled in Settings → General

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