Referrals

Referrals is an official Broadcast plugin. It gives each subscriber a personal link. When a new person signs up through that link, the subscriber gets a referral. At a number of referrals that you set, the subscriber earns a reward.

This page is for the owner of a newsletter. To read data from another system, see Referrals API.

Before you start

1. Install the Referrals plugin and turn it on in the channel. See Install, Update and Publish Plugins.
2. Open the settings of the plugin.
3. Enter the Signup page address. This is the page with your signup form. Each personal link points to this page, with the code of the subscriber at the end (?ref=r1vc5b).

The signup page can have a Broadcast form (see Opt-In Forms) or a form of your own. A Broadcast form keeps the code with no more work. For a form of your own, see A signup form of your own.

The page

Open Referrals in the plugins menu of the channel. The page has three numbers and three tabs.

A line under the numbers shows the pending referrals. A pending referral is a person who signed up through a link and is not confirmed.

Create a reward

1. Select New referral.
2. Fill in the Reward tab.
3. Select Save reward.

The form has three tabs. You can open them in any order. The preview at the right shows the referral block with the new reward, as a reader with no referrals sees it.

The Reward tab

A tag that is a topic is refused, because a topic is consent. The plugin log shows the refusal, and the referral still counts.

The Additional Settings tab

This tab has one switch, Auto Fulfill. With it, an earned reward is marked fulfilled at once. Use it for a reward that needs no work from you, such as a promo code. A Promo Code reward with no code left waits as pending.

The Milestone Email tab

The milestone email is one of the email templates of the channel (see Email Templates).

1. Choose a template in Template.
2. New template and Edit template open the template editor of Broadcast in a new tab. Select Refresh list when you come back.
3. Turn on Send Email After Review to hold the email until you mark the reward as fulfilled.

Rules for rewards

• A subscriber earns a reward one time.
• A reward that you make after a subscriber passed its number is not given to that subscriber.
• Actions in the rewards table has Edit, Delete and, for a Promo Code reward, Manage Promo Codes.

Promo codes

A Promo Code reward has a pool of codes. Each subscriber who earns the reward gets one code from the pool, one time.

1. In the rewards table, select Actions, then Manage Promo Codes.
2. Enter the codes, one on each line. You can add up to 1,000 codes at a time.
3. Select Add codes.

The dialog shows how many codes are left, for example “3 of 4 codes left”.

A code that is already in the pool is not added again. When the pool is empty, the earned reward waits as pending and the plugin log says so. The log also warns when 5 codes or fewer are left.

The Fulfillment tab

The Fulfillment tab lists each reward that a subscriber earned, newest first.

Actions on a row has these commands:

• Mark as Fulfilled, Mark as Ignored and Mark as Pending set the status.
• Manage Referrals shows the people whom the subscriber referred. Add 1 and Remove 1 correct the count by hand.

You can search by email and filter by status. The list shows 25 rows on a page and reads the newest 1,000 earned rewards.

Download Referrals copies the list to the clipboard as CSV. Paste it into a spreadsheet or a text file.

The referral block in your emails

The referral block is the part of an email that shows the reader their link, their count and their next reward.

Set up the block

Open the Configuration tab.

The preview under the settings changes as you choose.

Insert the block

1. Open a broadcast, a sequence email or a template in an editor.
2. Select Insert from a plugin. In the block editor, the block is under From plugins.
3. Select Referral program.
4. Select Insert referral block.

Each reader sees their own link, their own count and their own next reward. The texts of the block are in the language of the channel.

Merge tags

You can also write your own text with the merge tags of the plugin.

When a referral counts

• A referral counts when the new person is confirmed. Until then it is pending.
• A person counts one time.
• A person cannot refer themselves.
• A code that does not exist is ignored. The signup still works.

The plugin keeps the email of each referrer and of each referred person. When you delete a subscriber, the plugin deletes these records too.

A signup form of your own

A form of your own creates the subscriber with POST /api/v1/subscribers (see Subscribers API). It must pass the code on:

1. Read ref from the address of your signup page.
2. Send it as signup_ref inside subscriber.

{
  "subscriber": { "email": "new@example.com", "signup_ref": "r1vc5b" },
  "double_opt_in": true
}

With double_opt_in, the referral counts when the person confirms.

A subscriber that you create with no double opt-in is never confirmed, so the referral stays pending. If your form works that way, turn on Count a referral at signup in the settings of the plugin. The referral then counts when the person signs up.

Limits

• The Fulfillment tab reads the newest 1,000 earned rewards.
• The Overview tab shows the top 100 referrers.
• The plugin keeps its data in the plugin store of the channel, which holds 10 MB. Each referred person uses two small rows.