Skip to main content

​
API Reference

The Lettr API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

​
Base URL

https://api.lettr.dev/v1

​
Authentication

Authenticate requests using an API key in the Authorization header: 
curl https://api.lettr.dev/v1/emails \
  -H "Authorization: Bearer le_xxxxxxxxxxxx"

​
Request Format

Send JSON-encoded bodies with the appropriate Content-Type header: 
curl https://api.lettr.dev/v1/emails \
  -H "Authorization: Bearer le_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "you@example.com", "to": ["recipient@example.com"], "subject": "Hello", "html": "<p>Hello!</p>"}'

​
Response Format

All responses are JSON-encoded: 
{
  "id": "email_123abc",
  "object": "email",
  "from": "you@example.com",
  "to": ["recipient@example.com"],
  "subject": "Hello",
  "status": "sent",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
403Forbidden - Insufficient permissions
404Not Found
429Too Many Requests - Rate limited
500Server Error

​
Error Response

Errors return a consistent format: 
{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'to' field must be an array of email addresses",
    "param": "to"
  }
}

​
Pagination

List endpoints support pagination: 
curl "https://api.lettr.dev/v1/emails?limit=10&starting_after=email_123"
Response includes pagination info: 
{
  "data": [...],
  "hasMore": true,
  "totalCount": 150
}

​
Rate Limits

PlanLimit
Free10 requests/second
Pro100 requests/second
EnterpriseCustom
Rate limit headers are included in responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1673789400

​
API Endpoints

Emails

Send and manage emails

Domains

Manage sending domains

API Keys

Manage API keys

Webhooks

Configure webhooks