# Reletter API — full reference

> The newsletter data API. Search 6M+ email newsletters, fetch metadata, contacts, social accounts and rankings, and search the full text of newsletter issues. Built for integration with apps and AI agents.

This is the full API reference, optimized for LLM and agent consumption. For a shorter index, see [/llms.txt](/llms.txt). For the human-friendly portal, see [/developers](/developers).

We also provide:

- An official **Python client** and `reletter` CLI: `pip install reletter`. Source: https://github.com/getreletter/reletter-python
- A remote **MCP server** at `https://mcp.reletter.com` for Claude, ChatGPT, Cursor, and any other MCP client. Source: https://github.com/getreletter/reletter-mcp

---

## Authentication

All endpoints require the header:

```
x-reletter-api-key: YOUR_API_KEY
```

You can find your API key in your account settings at https://reletter.com/account/settings once you have an active Reletter subscription with the API add-on enabled.

Base URL: `https://api.reletter.com`

All responses are JSON over HTTPS.

## Errors

Errors return an HTTP status code (4xx or 5xx) and a JSON body of the form:

```json
{ "error": "Human-readable message", "code": "machine_code_optional" }
```

Common codes:

- `401` — `API key is unknown or inactive.` (invalid or missing key)
- `400` `api_quota_exceeded` — Monthly request quota reached.
- `429` `api_rate_limited` — Burst limit exceeded; back off and retry.
- `400` — Various validation errors with a human-readable message.

## Quotas

- **Monthly**: 10,000 requests per calendar month, resets on day 1.
- **Hourly**: 2,000 requests per team per hour, sliding window.

To check your usage:

```bash
curl -H "x-reletter-api-key: YOUR_API_KEY" \
  https://api.reletter.com/api/accounts/quota/
```

Response:

```json
{ "usage": 1284, "quota": 10000 }
```

---

## Search

### `GET /api/search/publications/`

Search the Reletter index for newsletters by topic, title or author. Supports rich filters for language, subscriber count, engagement, platform and more.

**Query parameters:**

- `query` (string, required) — Search query.
- `mode` (string, optional, default `topics`) — One of `topics`, `titles`, `authors`.
- `page` (integer, default 1) — Page number.
- `per_page` (integer, default 25, max 100) — Results per page.
- `filters` (string, optional) — Comma-separated filters. Each filter is `field:op:value`. Examples: `active:is:true`, `engagement:gte:50`, `subscribers:gte:5000`, `language:is:en`.

**Example:**

```bash
curl -H "x-reletter-api-key: YOUR_API_KEY" \
  "https://api.reletter.com/api/search/publications/?query=climate&mode=topics&filters=engagement:gte:50,subscribers:gte:5000"
```

**Response:**

```json
{
  "page": 1,
  "per_page": 25,
  "count": 124,
  "more": true,
  "spelling_suggestion": null,
  "exact_matches": [],
  "publications": [
    {
      "id": "doomberg",
      "platform": "substack",
      "url": "https://newsletter.doomberg.com",
      "name": "Doomberg",
      "description": "A lateral-thinking approach to energy, finance, and geopolitics.",
      "founded": "2021-04-21T18:58:46Z",
      "subscribers": 373000,
      "engagement": 92,
      "language": "en",
      "issue_frequency": "twiceweekly",
      "publishing_model": "freemium",
      "num_issues": 496,
      "active": true,
      "sponsored": false
    }
  ]
}
```

### `GET /api/search/issues/`

Full-text search across the body and titles of every newsletter issue Reletter has indexed. Returns highlighted snippets when `highlight=true`.

**Query parameters:**

- `query` (string, required) — Search query.
- `highlight` (boolean) — Include highlighted snippets.
- `threshold` (integer) — Only include issues newer than this many seconds.
- `page` (integer, default 1).
- `per_page` (integer, default 25, max 100).

**Response:**

```json
{
  "page": 1,
  "per_page": 25,
  "count": 12,
  "more": false,
  "spelling_suggestion": null,
  "issues": [
    {
      "id": "pdh-the-coal-paradox",
      "title": "The Coal Paradox",
      "contributors": ["Doomberg"],
      "published": "2026-04-22T13:01:00Z",
      "num_likes": 412,
      "num_comments": 28,
      "url": "https://newsletter.doomberg.com/p/the-coal-paradox",
      "image_url": "https://substackcdn.com/image/...",
      "type": "newsletter",
      "substack_slug": "the-coal-paradox",
      "substack_podcast_url": null,
      "text": "... full body text ...",
      "highlight": {
        "title": null,
        "text": ["... rising <em>coal</em> demand ..."]
      },
      "publication": {
        "id": "doomberg",
        "platform": "substack",
        "name": "Doomberg"
      }
    }
  ]
}
```

### `GET /api/search/autocomplete/`

Autocomplete suggestions for the start of a query. Designed for type-ahead UIs.

**Query parameters:**

- `query` (string, required) — Query prefix.
- `mode` (string, required) — `topics`, `titles`, `authors`, `issues`.

**Response:**

```json
{
  "suggestions": [],
  "publications": [
    { "id": "doomberg", "name": "Doomberg", "platform": "substack" },
    { "id": "noahpinion", "name": "Noahpinion", "platform": "substack" }
  ]
}
```

---

## Publications

### `GET /api/publications/<publication_id>/`

Full metadata for a single publication: subscribers, engagement, social, contributors, rankings, latest issues, badges.

**Response:**

```json
{
  "publication": {
    "id": "doomberg",
    "platform": "substack",
    "url": "https://newsletter.doomberg.com",
    "name": "Doomberg",
    "short_name": "Doomberg",
    "description": "A lateral-thinking approach to energy, finance, and geopolitics.",
    "artwork_url": "https://substackcdn.com/image/...",
    "founded": "2021-04-21T18:58:46Z",
    "subscribers": 373000,
    "added": "2023-02-08T12:45:40Z",
    "active": true,
    "language": "en",
    "engagement": 92,
    "sponsored": false,
    "estimated_ad_cost": {
      "min_cpm": 1000, "max_cpm": 3000,
      "min_cost": 373000, "max_cost": 1119000
    },
    "est_monthly_visits": 63308,
    "issue_frequency": "twiceweekly",
    "num_issues": 496,
    "publishing_model": "freemium",
    "contributors": [{ "id": "doomberg", "name": "Doomberg", "platform": "substack" }],
    "social": [{ "channel": "twitter", "identifier": "DoombergT", "followers": 162000 }],
    "rankings": [{ "platform": "substack", "category": "finance", "position": 4 }],
    "badges": ["top-100"]
  }
}
```

---

## Issues

### `GET /api/issues/?publication_id=<id>`

Recent issues for a given publication, in chronological order (newest first).

**Query parameters:**

- `publication_id` (string, required).

**Response:**

```json
{
  "issues": [
    {
      "id": "pdh-the-coal-paradox",
      "title": "The Coal Paradox",
      "contributors": ["Doomberg"],
      "published": "2026-04-22T13:01:00Z",
      "num_likes": 412,
      "num_comments": 28,
      "url": "https://newsletter.doomberg.com/p/the-coal-paradox",
      "image_url": "https://substackcdn.com/image/...",
      "type": "newsletter",
      "substack_slug": "the-coal-paradox",
      "substack_podcast_url": null,
      "text": "... full body text ..."
    }
  ]
}
```

### `GET /api/issues/<issue_id>/`

Full data for a single issue, including the body text and the publication it belongs to.

**Response:**

```json
{
  "issue": {
    "id": "pdh-the-coal-paradox",
    "title": "The Coal Paradox",
    "contributors": ["Doomberg"],
    "published": "2026-04-22T13:01:00Z",
    "num_likes": 412,
    "num_comments": 28,
    "url": "https://newsletter.doomberg.com/p/the-coal-paradox",
    "image_url": "https://substackcdn.com/image/...",
    "type": "newsletter",
    "substack_slug": "the-coal-paradox",
    "substack_podcast_url": null,
    "text": "... full body text ...",
    "publication": {
      "id": "doomberg",
      "platform": "substack",
      "name": "Doomberg",
      "subscribers": 373000
    }
  }
}
```

---

## Contacts

### `GET /api/contacts/?publication_id=<id>`

Email contacts, social accounts, and contributor profiles for a publication.

**Response:**

```json
{
  "fetchable": false,
  "contacts": {
    "email": [
      {
        "full_name": "Doomberg Editorial",
        "email": "editorial@doomberg.com",
        "category": "general",
        "verification_status": "valid"
      }
    ],
    "social": [
      {
        "channel": "twitter",
        "identifier": "DoombergT",
        "url": "https://twitter.com/DoombergT",
        "added": "2023-02-08T12:45:40Z"
      }
    ],
    "contributors": [
      {
        "id": "doomberg",
        "platform": "substack",
        "name": "Doomberg",
        "bio": "A lateral-thinking team writing on energy and markets.",
        "social": [],
        "owner": true
      }
    ]
  }
}
```

---

## Charts

### `GET /api/charts/`

Index of available chart platforms and their categories. Use the returned slugs with `/api/charts/<platform>/<category>/`.

**Response:**

```json
{
  "reletter": [{ "id": "top-50", "name": "Reletter Top 50", "variants": null }],
  "linkedin": [{ "id": "top-50", "name": "LinkedIn Top 50", "variants": null }],
  "substack": [
    { "id": "top-50", "name": "Substack Top 50", "variants": null },
    { "id": "finance", "name": "Finance", "variants": ["paid", "free"] }
  ]
}
```

### `GET /api/charts/<platform>/<category>/`

Chart rankings on a given platform / category. Each entry is a full publication dict, ordered by rank.

**Query parameters:**

- `variant` (string, optional) — `paid`, `free`, `rising`, etc. (where supported).

**Response:**

```json
{
  "name": "Finance",
  "platform": "substack",
  "variant": null,
  "publications": [
    {
      "id": "doomberg",
      "platform": "substack",
      "name": "Doomberg",
      "subscribers": 373000,
      "engagement": 92
    }
  ]
}
```

---

## Account

### `GET /api/accounts/quota/`

Returns your current usage and quota for the calendar month.

**Response:**

```json
{ "usage": 1284, "quota": 10000 }
```

---

## Terms of use

By using the Reletter API you agree that:

1. You will not use the API to build a product that competes directly with Reletter.
2. You will not resell direct API access.
3. You will not store API responses permanently on your servers. Short-term caching for performance is fine. Temporary storage for analysis or model inference is allowed.
4. We may revoke API access for any application that breaks these terms.
5. You can email support@reletter.com to discuss exemptions.