> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Complete reference for the Lettr REST API, with resource-oriented URLs, JSON requests and responses, Bearer authentication, and HTTP codes.

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:

```bash theme={null}
curl https://app.lettr.com/api/emails \
  -H "Authorization: Bearer lttr_xxxxxxxxxxxx"
```

## Request Format

Send JSON-encoded bodies with the appropriate Content-Type header:

```bash theme={null}
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):**

```json theme={null}
{
  "message": "Email queued for delivery.",
  "data": {
    "request_id": "12345678901234567890",
    "accepted": 1,
    "rejected": 0
  }
}
```

**Error response (400, 502):**

```json theme={null}
{
  "message": "The sender domain is not configured or approved for sending.",
  "error_code": "unconfigured_domain"
}
```

**Validation error response (422):**

```json theme={null}
{
  "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

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

## Error Codes

| Code                   | HTTP Status | Description                                                                       |
| ---------------------- | ----------- | --------------------------------------------------------------------------------- |
| `validation_error`     | 422         | Request validation failed. Check the `errors` object for field-specific messages. |
| `invalid_domain`       | 400         | The sender domain could not be determined from the email address.                 |
| `unconfigured_domain`  | 400         | The sender domain is not configured or approved for sending.                      |
| `send_error`           | 400         | General error during email send preparation.                                      |
| `rate_limit_exceeded`  | 429         | Too many API requests. Slow down and retry after the `Retry-After` period.        |
| `quota_exceeded`       | 429         | Monthly sending quota exceeded. Upgrade your plan to continue sending.            |
| `daily_quota_exceeded` | 429         | Daily sending quota exceeded (free tier). Try again tomorrow.                     |
| `transmission_failed`  | 502         | Email 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:

| Option           | Type    | Default | Description                                                                 |
| ---------------- | ------- | ------- | --------------------------------------------------------------------------- |
| `transactional`  | boolean | `true`  | Whether this is a transactional email. Set to `false` for marketing emails. |
| `open_tracking`  | boolean | `false` | Track email opens                                                           |
| `click_tracking` | boolean | `false` | Track link clicks                                                           |

<Note>
  Since `transactional` defaults to `true`, you only need to explicitly set it when sending marketing emails (`transactional: false`).
</Note>

### 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

```json theme={null}
{
  "headers": {
    "X-My-Header": "custom-value",
    "X-Campaign-ID": "spring-2026"
  }
}
```

<Warning>
  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`
</Warning>

## API Endpoints

<CardGroup cols={2}>
  <Card title="Send Email" icon="envelope" href="/api-reference/emails/send-email">
    Send emails to one or more recipients
  </Card>

  <Card title="Templates" icon="file-lines" href="/api-reference/templates/list-templates">
    Manage templates, merge tags, and rendered HTML
  </Card>

  <Card title="Domains" icon="globe" href="/api-reference/domains/list-domains">
    Create, verify, and manage sending domains
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/list-webhooks">
    View webhook configurations
  </Card>
</CardGroup>