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://app.uselettr.com/api/

​
Authentication

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

​
Request Format

Send JSON-encoded bodies with the appropriate Content-Type header: 
curl -X POST https://app.uselettr.com/api/emails \
  -H "Authorization: Bearer le_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"from": "[email protected]", "to": ["[email protected]"], "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
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.
transmission_failed502Email transmission to the upstream provider failed.

​
API Endpoints

Send Email

Send emails to one or more recipients