Skip to main content
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://app.lettr.com/api/

Authentication

Authenticate requests using an API key in the Authorization header:
curl https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"

Request Format

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

Response Format

Success response (200):
{
  "message": "Email queued for delivery.",
  "data": {
    "request_id": "12345678901234567890",
    "accepted": 1,
    "rejected": 0
  }
}
Error response (400, 502):
{
  "message": "The sender domain is not configured or approved for sending.",
  "error_code": "unconfigured_domain"
}
Validation error response (422):
{
  "message": "Validation failed.",
  "error_code": "validation_error",
  "errors": {
    "from": ["The sender email address is required."],
    "to": ["At least one recipient email address is required."]
  }
}

HTTP Status Codes

CodeDescription
200Success - Email queued for delivery
400Bad Request - Domain configuration error
401Unauthorized - Invalid or missing API key
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit or sending quota exceeded
502Bad Gateway - Upstream transmission failed

Error Codes

CodeHTTP StatusDescription
validation_error422Request validation failed. Check the errors object for field-specific messages.
invalid_domain400The sender domain could not be determined from the email address.
unconfigured_domain400The sender domain is not configured or approved for sending.
send_error400General error during email send preparation.
rate_limit_exceeded429Too many API requests. Slow down and retry after the Retry-After period.
quota_exceeded429Monthly sending quota exceeded. Upgrade your plan to continue sending.
daily_quota_exceeded429Daily sending quota exceeded (free tier). Try again tomorrow.
transmission_failed502Email transmission to the upstream provider failed.

API Endpoints