Custom Integration

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.

​

Getting started with API access

​

1. Obtain your API key

1. Sign up for the trial at letterby.com
2. Your API key will remain active during development
3. We’ll ensure it doesn’t auto-renew until your integration is complete and live

​

Waitlist registration

​

Creating contacts

curl --request POST \
  --url https://letterby.com/api/v4/contacts \
  --header 'Content-Type: application/json' \
  --header 'apiKey: YOUR_API_KEY' \
  --data '{
    "email": "user@example.com",
    "name": "John Doe"
  }'

​

What happens after contact creation

1. Verification Email: An automatic verification email is sent to the user
2. Confirmation: When they click the verification link, they’re redirected to their rank page
3. Referral System: On their rank page, users can invite friends to move up faster

​

Core integration: point system

​

Understanding the point system

​

Awarding points with the actions endpoint

curl --request POST \
  --url https://letterby.com/api/v4/actions \
  --header 'Content-Type: application/json' \
  --header 'apiKey: YOUR_API_KEY' \
  --data '{
    "name": "Purchased 1K Plan",
    "increase": 10,
    "contactId": "contact_123"
  }'

​

Parameters explained

• name: A descriptive name for the action (e.g., “Purchased 1K Plan”, “Shared on Social Media”)
• increase: The number of points to award (can be any positive integer)
• contactId: The unique identifier of the contact who performed the action

​

Common point-worthy actions

• Referral Success: +50 points when someone they invited joins
• Social Media Share: +10 points for sharing your product
• Purchase Plans: +25 points for upgrading to paid plans
• Profile Completion: +5 points for completing their profile
• Daily Login: +1 point for logging in each day

​

Customizing the user experience

​

Email verification settings

1. Go to Journey → Confirmation Email
2. Customize the email template, subject line, and styling
3. Preview and test your changes

​

Referral page customization

​

Option 1: Use Letterby hosted page (recommended)

• Go to Journey → Referral Page in your dashboard
• Customize colors, branding, and messaging
• Users are automatically redirected here after verification

​

Option 2: Self-hosted custom page

• Contact our support team to enable the self-hosted verification endpoint
• You’ll handle verification manually when users click confirmation links
• Requires additional development and maintenance

​

Complete integration example

class LetterbyIntegration {
	constructor(apiKey) {
		this.apiKey = apiKey
		this.baseUrl = 'https://letterby.com/api/v4'
	}

	async addToWaitlist(email, name) {
		try {
			const response = await fetch(`${this.baseUrl}/contacts`, {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json',
					apiKey: this.apiKey,
				},
				body: JSON.stringify({ email, name }),
			})

			const contact = await response.json()
			return contact
		} catch (error) {
			console.error('Failed to add contact:', error)
			throw error
		}
	}

	async awardPoints(contactId, actionName, points) {
		try {
			const response = await fetch(`${this.baseUrl}/actions`, {
				method: 'POST',
				headers: {
					'Content-Type': 'application/json',
					apiKey: this.apiKey,
				},
				body: JSON.stringify({
					contactId,
					name: actionName,
					increase: points,
				}),
			})

			const action = await response.json()
			return action
		} catch (error) {
			console.error('Failed to award points:', error)
			throw error
		}
	}
}

// Usage example
const waitless = new LetterbyIntegration('YOUR_API_KEY')

// Add user to waitlist
const contact = await waitless.addToWaitlist('user@example.com', 'John Doe')

// Award points for completing profile
await waitless.awardPoints(contact.id, 'Profile Completed', 5)

// Award points for referral
await waitless.awardPoints(contact.id, 'Successful Referral', 50)

​

Best practices

​

Security

• Always validate user input before making API calls
• Never expose your API key in client-side code
• Use environment variables to store sensitive data

​

Point economy

• Design a balanced point system that encourages engagement without being too easy
• Consider diminishing returns for repeated actions (daily login caps, etc.)
• Make high-value actions worth significantly more points

​

User experience

• Provide clear feedback when users earn points
• Show progress towards their next rank or reward
• Make the referral process as simple as possible

​

Troubleshooting

​

Common issues

• Ensure the email format is valid
• Check that the contact doesn’t already exist
• Verify your API key has the correct permissions

• Confirm the contact exists before awarding points
• Check that the contactId is correct
• Ensure increase is a positive integer

• Check your dashboard settings under Journey → Confirmation Email
• Verify the email isn’t being caught by spam filters
• Contact support if emails consistently fail to deliver

​

Next steps

1. Set up monitoring and analytics to track user engagement
2. Experiment with different point values to optimize user behavior
3. Consider implementing webhook notifications for real-time updates
4. Explore advanced features like Audiences for targeted campaigns

​

Getting help

• Check our API Reference for detailed endpoint documentation
• Join our Discord community for quick help
• Contact support at hi@letterby.com for enterprise support