Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.letterby.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Building referrals and rewards

Referrals and rewards are the heart of any successful waitlist. They create viral loops that drive organic growth while keeping users engaged. This guide will show you how to implement both systems using Letterby.

​
Understanding the referral system

Letterby automatically generates unique referral links for each contact. When someone signs up using a referral link, both the referrer and referee benefit:
  • Referrer: Gets points and moves up in the waitlist
  • Referee: May get bonus points for being referred
  • You: Get organic growth and higher conversion rates

​
How referrals work

  1. Each contact gets a unique referralLink when they join
  2. When someone clicks their referral link and signs up, the referrer’s referrals count increases
  3. You can reward the referrer with points using the Actions API
  4. The system tracks everything automatically

​
Setting up referral rewards

​
1. Track referral events

When a new user signs up through a referral link, Letterby automatically:
  • Increments the referrer’s referrals count
  • Tracks the connection between referrer and referee
You can then award points to the referrer for successful referrals: 
// Award points to a referrer for successful referral
async function rewardReferral(referrerContactId, referredEmail) {
	try {
		// Award points to the referrer
		const response = await fetch('https://letterby.com/api/v4/actions', {
			method: 'POST',
			headers: {
				'Content-Type': 'application/json',
				apiKey: 'YOUR_API_KEY',
			},
			body: JSON.stringify({
				contactId: referrerContactId,
				name: `Referred ${referredEmail}`,
				increase: 50, // 50 points for successful referral
			}),
		})

		const result = await response.json()
		console.log('Referral reward added:', result)
	} catch (error) {
		console.error('Failed to reward referral:', error)
	}
}

​
2. Reward the referee

You can also give bonus points to new users who were referred: 
// Give bonus points to someone who was referred
async function rewardReferee(newContactId, referrerName) {
	try {
		const response = await fetch('https://letterby.com/api/v4/actions', {
			method: 'POST',
			headers: {
				'Content-Type': 'application/json',
				apiKey: 'YOUR_API_KEY',
			},
			body: JSON.stringify({
				contactId: newContactId,
				name: `Referred by ${referrerName}`,
				increase: 10, // 10 bonus points for being referred
			}),
		})

		const result = await response.json()
		console.log('Referee bonus added:', result)
	} catch (error) {
		console.error('Failed to reward referee:', error)
	}
}

​
Building a comprehensive reward system

​
Common reward scenarios

Here are effective reward strategies that drive engagement:

​
Social sharing rewards

// Reward users for sharing on social media
const socialRewards = {
	twitter: { points: 15, name: 'Shared on Twitter' },
	linkedin: { points: 15, name: 'Shared on LinkedIn' },
	facebook: { points: 10, name: 'Shared on Facebook' },
	instagram: { points: 20, name: 'Shared on Instagram Story' },
}

async function rewardSocialShare(contactId, platform) {
	const reward = socialRewards[platform]
	if (!reward) return

	await fetch('https://letterby.com/api/v4/actions', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			apiKey: 'YOUR_API_KEY',
		},
		body: JSON.stringify({
			contactId,
			name: reward.name,
			increase: reward.points,
		}),
	})
}

​
Engagement rewards

// Reward daily engagement
async function rewardDailyCheckin(contactId) {
	await fetch('https://letterby.com/api/v4/actions', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			apiKey: 'YOUR_API_KEY',
		},
		body: JSON.stringify({
			contactId,
			name: 'Daily check-in',
			increase: 2, // Small daily reward
		}),
	})
}

​
Milestone rewards

Create special rewards for reaching certain milestones: 
async function checkAndRewardMilestones(contactId) {
	// Get contact details to check current stats
	const contact = await fetch(
		`https://letterby.com/api/v4/contacts/${contactId}`,
		{
			headers: { apiKey: 'YOUR_API_KEY' },
		},
	).then(res => res.json())

	const { referrals, points } = contact.data.contact

	// Referral milestones
	const referralMilestones = [
		{ count: 5, reward: 100, name: 'First 5 referrals bonus' },
		{ count: 10, reward: 250, name: 'First 10 referrals bonus' },
		{ count: 25, reward: 500, name: 'Super referrer bonus' },
	]

	// Point milestones
	const pointMilestones = [
		{ count: 100, reward: 50, name: 'First 100 points milestone' },
		{ count: 500, reward: 100, name: 'Power user milestone' },
		{ count: 1000, reward: 200, name: 'Elite member milestone' },
	]

	// Check and award milestone rewards
	// (You'd need to track which milestones were already awarded)
}

​
Advanced referral strategies

​
Tiered referral rewards

Create increasing rewards for multiple referrals: 
const referralTiers = [
	{ min: 1, max: 2, points: 25, name: 'Referral reward' },
	{ min: 3, max: 4, points: 35, name: 'Active referrer bonus' },
	{ min: 5, max: 9, points: 50, name: 'Super referrer bonus' },
	{ min: 10, max: Infinity, points: 75, name: 'Elite referrer bonus' },
]

async function getRewardForReferralCount(referralCount) {
	const tier = referralTiers.find(
		t => referralCount >= t.min && referralCount <= t.max,
	)
	return tier || referralTiers[0]
}

​
Limited-time bonus campaigns

Create urgency with temporary bonus rewards: 
async function applyBonusCampaign(contactId, actionName, basePoints) {
	const now = new Date()
	const isWeekend = now.getDay() === 0 || now.getDay() === 6
	const isHappyHour = now.getHours() >= 18 && now.getHours() <= 20

	let multiplier = 1
	let bonusName = actionName

	if (isWeekend) {
		multiplier = 1.5
		bonusName += ' (Weekend Bonus)'
	}

	if (isHappyHour) {
		multiplier *= 1.2
		bonusName += ' (Happy Hour)'
	}

	const finalPoints = Math.floor(basePoints * multiplier)

	await fetch('https://letterby.com/api/v4/actions', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			apiKey: 'YOUR_API_KEY',
		},
		body: JSON.stringify({
			contactId,
			name: bonusName,
			increase: finalPoints,
		}),
	})
}

​
Retrieving referral data

​
Get a contact’s referral information

You can retrieve referral stats for any contact: 
async function getReferralStats(contactId) {
	try {
		const response = await fetch(
			`https://letterby.com/api/v4/contacts/${contactId}`,
			{
				headers: {
					apiKey: 'YOUR_API_KEY',
				},
			},
		)

		const result = await response.json()
		const contact = result.data.contact

		return {
			referralLink: contact.referralLink,
			referralCount: contact.referrals,
			totalPoints: contact.points,
			position: contact.position,
		}
	} catch (error) {
		console.error('Failed to get referral stats:', error)
	}
}

​
Track action history

See all rewards a contact has earned: 
async function getContactActions(contactId) {
	try {
		const response = await fetch(
			`https://letterby.com/api/v4/actions?contactId=${contactId}`,
			{
				headers: {
					apiKey: 'YOUR_API_KEY',
				},
			},
		)

		const result = await response.json()
		return result.data.actions
	} catch (error) {
		console.error('Failed to get actions:', error)
	}
}

​
Best practices for referrals and rewards

​
Design effective reward structures

  1. Make referrals valuable: Offer meaningful rewards (25-100 points) for successful referrals
  2. Reward both parties: Give bonuses to both referrer and referee
  3. Create urgency: Use limited-time bonuses and campaigns
  4. Gamify progression: Create milestones and achievement levels

​
Technical implementation tips

  1. Validate actions: Ensure users can’t game the system
  2. Rate limiting: Prevent abuse with reasonable limits
  3. Clear communication: Always tell users what they earned and why
  4. Analytics: Track which rewards drive the most engagement

​
Common reward values

Based on successful Waitlist campaigns:
  • Referral completion: 25-100 points
  • Social media shares: 10-25 points
  • Profile completion: 5-50 points (based on complexity)
  • Daily check-ins: 1-5 points
  • Newsletter signup: 15-30 points
  • Milestone bonuses: 50-500 points

​
Measuring success

Track these key metrics to optimize your referral and reward system:
  • Referral conversion rate: Percentage of referral link clicks that convert
  • Average referrals per user: How viral is your waitlist?
  • Point distribution: Which rewards are most popular?
  • Engagement over time: Are rewards keeping users active?
Want to see this in action? Check out our complete integration example for a full implementation that includes referrals and rewards.

​
Troubleshooting

​
Common issues

Referral links not working
  • Ensure contacts are verified before their referral links become active
  • Check that the referring contact exists and is valid
Points not being awarded
  • Verify the contact ID is correct
  • Ensure the action name is descriptive and unique
  • Check that your API key has the proper permissions
Duplicate rewards
  • Implement checks to prevent duplicate rewards for the same action
  • Use unique action names that include timestamps or unique identifiers
Remember: A well-designed referral and reward system can increase your waitlist signups by 3-5x while keeping users highly engaged throughout their journey!