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.

This API documentation covers all endpoints available in the Letterby API v4.

​
Welcome

Welcome to the Letterby API documentation. Our API enables you to programmatically manage your contacts, actions, projects and audiences. This documentation provides detailed information about the available endpoints and how to use them.

​
Authentication

All API endpoints require authentication using an API key in the header. To obtain an API key:
  1. Go to letterby.com/admin/lists
  2. Click on your project
  3. Navigate to the Integrations tab
  4. Click “Create key”

​
API Key Types

Letterby offers two types of API keys to suit different use cases:

​
Private Keys

  • Usage: Server-to-server communication, backend integrations
  • Access: Full CRUD access to all endpoints
  • Security: Keep these secure - never expose in client-side code
  • Example use: Backend services, server scripts, cron jobs

​
Public Keys

  • Usage: Client-side applications, frontend integrations
  • Access: Create contacts only (no read, update, or delete access)
  • Security: Safe for client-side use with limited permissions
  • Example use: Signup forms, contact creation widgets, mobile apps

​
Key Features

  • Rate Limiting: All keys are rate-limited by Cloudflare
  • Expiration: Keys can be set to expire automatically
  • Active/Inactive: Keys can be enabled/disabled instantly

​
Using API Keys

​
Basic Authentication

All requests require the apiKey header: 
curl -X GET "https://letterby.com/api/v4/contacts" \
  -H "Content-Type: application/json" \
  -H "apiKey: your-private-api-key"

​
Public Keys Usage

Public keys are designed for client-side use and can only create contacts: 
curl -X POST "https://letterby.com/api/v4/contacts" \
  -H "Content-Type: application/json" \
  -H "apiKey: your-public-api-key" \
  -d '{"email": "user@example.com", "listId": "your-list-id"}'

​
JavaScript/Frontend Usage

For browser-based applications, public keys work seamlessly: 
fetch('https://letterby.com/api/v4/contacts', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		apiKey: 'your-public-api-key',
	},
	body: JSON.stringify({
		email: 'user@example.com',
		listId: 'your-list-id',
	}),
})
Key Security: Private keys should never be exposed in client-side code. Use Public keys for frontend applications and Private keys for backend services.

​
Rate Limiting

To ensure the stability of our service, API requests are rate limited by Cloudflare:
  • 100 requests per minute for free accounts
  • 1000 requests per minute for pro accounts
If you exceed these limits, you’ll receive a 429 Too Many Requests response.

​
Response Format

All responses are returned in JSON format and include either the requested data or an error object: 
// Success response
{
  "data": {
    // Response data
  }
}

// Error response
{
  "error": "Error message"
}

​
Getting Started

To get started with the API, first obtain your API key following the steps above. Then, try making a simple request to list your projects: 
curl -X GET "https://letterby.com/api/v4/projects" \
  -H "apiKey: your-private-api-key"