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.

​
Send Email Reference

​
Subject

The subject field is conditionally required:
  • Required when sending with html or text content directly.
  • Optional when template_slug is provided — if omitted, Lettr uses the template’s stored subject. If the template has no subject set, the template name is used instead.
  • If provided alongside a template_slug, the subject overrides the template’s subject. This is useful for A/B testing or dynamic subject lines.
Maximum length: 998 characters.

​
Options

The options object controls tracking and email classification:
OptionTypeDefaultDescription
transactionalbooleantrueWhether this is a transactional email. Set to false for marketing emails.
open_trackingbooleanfalseTrack email opens
click_trackingbooleanfalseTrack link clicks
Since transactional defaults to true, you only need to explicitly set it when sending marketing emails (transactional: false).

​
Custom Headers

The headers field lets you add custom email headers to your message. Pass an object where each key is the header name and each value is the header value. Limits:
  • Maximum 10 custom headers per email
  • Maximum 998 characters per header value
{
  "headers": {
    "X-My-Header": "custom-value",
    "X-Campaign-ID": "spring-2026"
  }
}
The following headers are blocked and cannot be set via the headers field — Lettr manages them automatically:From, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, MIME-Version, Content-Type, Content-Transfer-Encoding, DKIM-Signature, Return-Path, Received, List-Unsubscribe, List-Unsubscribe-Post

​
API Endpoints

Send Email

Send emails to one or more recipients

Templates

Manage templates, merge tags, and rendered HTML

Domains

Create, verify, and manage sending domains

Webhooks

View webhook configurations