> ## 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.

# Custom Integration

> Complete guide to integrating Letterby into your system with point rewards and waitlist management.

## Getting started with API access

### 1. Obtain your API key

The most secure way to get access to the Letterby API is through our **7-day
trial**:

1. Sign up for the trial at [letterby.com](https://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

<Warning>
  Keep your API key secure and never expose it in client-side code. Always use
  it server-side only.
</Warning>

## Waitlist registration

### Creating contacts

To add users to your waitlist, use the
[Create Contact endpoint](/api-reference/endpoint/contact-create). This endpoint
automatically handles the verification process.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://letterby.com/api/v4/contacts', {
  	method: 'POST',
  	headers: {
  		'Content-Type': 'application/json',
  		apiKey: 'YOUR_API_KEY',
  	},
  	body: JSON.stringify({
  		email: 'user@example.com',
  		name: 'John Doe',
  	}),
  })
  ```
</CodeGroup>

### 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

Letterby uses an action-based point system where users earn points for specific
actions they perform. This encourages engagement and moves them up the waitlist.

### Awarding points with the actions endpoint

To award points to a user, you'll use the
[Actions endpoint](/api-reference/endpoint/action-create). The contact must
already exist in your system before you can award points.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://letterby.com/api/v4/actions', {
  	method: 'POST',
  	headers: {
  		'Content-Type': 'application/json',
  		apiKey: 'YOUR_API_KEY',
  	},
  	body: JSON.stringify({
  		name: 'Purchased 1K Plan',
  		increase: 10,
  		contactId: 'contact_123',
  	}),
  })
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://letterby.com/api/v4/actions',
      headers={
          'Content-Type': 'application/json',
          'apiKey': 'YOUR_API_KEY'
      },
      json={
          'name': 'Purchased 1K Plan',
          'increase': 10,
          'contactId': 'contact_123'
      }
  )
  ```
</CodeGroup>

### 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

Here are some common actions you might want to reward:

* **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

You can customize the verification email from your dashboard:

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

### Referral page customization

You have two options for the referral page:

#### 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

If you need complete control over the user experience, we offer a special
endpoint for self-hosting:

<Warning>
  Self-hosting is only recommended if you need a completely custom page. The
  hosted solution covers most use cases and is much easier to implement.
</Warning>

* 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

Here's a complete example showing how to implement both contact creation and
point awarding:

```javascript theme={null}
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

**Contact creation fails**

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

**Points not awarded**

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

**Verification emails not sending**

* 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

Once you have the basic integration working:

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](/api-reference/endpoint/audience-create) for targeted campaigns

## Getting help

If you need assistance with your integration:

* Check our [API Reference](/api-reference/introduction) for detailed endpoint
  documentation
* Join our [Discord community](https://discord.gg/KCqQsY8Atn) for quick help
* Contact support at [hi@letterby.com](mailto:hi@letterby.com) for enterprise
  support

<Info>
  Remember: Your API key will remain active during development and won't
  auto-renew until your integration is complete and live. Take your time to
  build a solid implementation!
</Info>