# Reletter API

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

Reletter provides a REST API for accessing structured newsletter data. The API is designed for integration with your apps and AI agents.

We also provide this as an MCP server at `https://mcp.reletter.com`, and as an official Python SDK and `reletter` CLI (`pip install reletter`).

## API host

**The API is on `https://api.reletter.com`, not `https://reletter.com`.** Every `/api/*` path in this document — including the unauthenticated `/api/payments/bundles/` and `/api/payments/buy/` bootstrap endpoints — is served from the `api.` subdomain. The apex `reletter.com` domain serves the marketing site and will return HTML 404s for API paths.

Quick verify:

```sh
curl https://api.reletter.com/api/payments/bundles/
```

## Documentation

- [Complete API reference (Markdown)](/llms-full.txt): Full endpoint documentation optimized for LLM consumption.
- [Developer portal](/developers): Human-readable documentation with examples, pricing, and signup.
- [Python client on GitHub](https://github.com/getreletter/reletter-python): Official Python SDK and `reletter` CLI. Typed wrapper around every endpoint, sync and async. `pip install reletter` (or `pipx install reletter` for CLI-only use).
- [MCP server on GitHub](https://github.com/getreletter/reletter-mcp): Remote MCP server at `https://mcp.reletter.com` for Claude, ChatGPT, Cursor, etc.

## Authentication

All `/api/*` endpoints require the `x-reletter-api-key` header containing your API key, except `GET /api/payments/bundles/` and `POST /api/payments/buy/`, which are unauthenticated since they exist to bootstrap a key. Two ways to get a key:

1. **Dashboard** (humans, monthly billing): sign up at [reletter.com](https://reletter.com), pick a plan, add the API add-on, copy your key from [account settings](/account/settings).
2. **Programmatic / agent purchase** (HTTP 402, no signup): `POST https://api.reletter.com/api/payments/buy/` returns a `402 Payment Required` advertising two settlement methods — `stripe` (Shared Payment Token, card/wallet, synchronous) and `tempo` (USDC on Tempo, asynchronous). Pay with either and the response contains your API key. Bundle tiers and current prices: `GET https://api.reletter.com/api/payments/bundles/`. See `/llms-full.txt` for the full flow. Compatible with the IETF MPP draft (draft-ryan-httpauth-payment) and [mpp.dev](https://mpp.dev).

## Quotas and limits

- Default quota: 10,000 requests per calendar month, resets on the 1st of the month.
- Hourly burst limit: 2,000 requests per hour per team. The API returns HTTP 429 if you exceed it.
- Need higher limits? Email support@reletter.com.

## Available endpoints

All paths below are on `https://api.reletter.com`.

- `GET /api/search/publications/` — Search newsletters by topic, title or author. Supports a `filters` query parameter with the syntax `name:operator:value` (comma-separated), e.g. `?filters=active:is:true,subscribers:gte:5000,languages:any:en`. Full filter reference: [/developers/search-filters](/developers/search-filters) and [/llms-full.txt](/llms-full.txt#search-filters).
- `GET /api/search/issues/` — Full-text search across newsletter issue bodies. Accepts the same `filters` parameter as publication search; filters apply to the parent publication.
- `GET /api/search/autocomplete/` — Autocomplete suggestions for type-ahead UIs.
- `GET /api/publications/<publication_id>/` — Full metadata for a publication.
- `GET /api/issues/?publication_id=<id>` — List recent issues for a publication.
- `GET /api/issues/<issue_id>/` — Get a single issue with body text.
- `GET /api/contacts/?publication_id=<id>` — Email and social contacts for a publication.
- `GET /api/charts/` — Index of chart platforms and categories.
- `GET /api/charts/<platform>/<category>/` — Chart rankings.
- `GET /api/misc/languages/` — Reference list of supported language codes (for the `languages` search filter).
- `GET /api/misc/stats/` — Global Reletter index stats (publications, issues, social accounts).
- `GET /api/accounts/quota/` — Your current API usage and quota.
- `GET /api/payments/bundles/` — Available pay-per-bundle tiers for agent purchase (no auth required).
- `POST /api/payments/buy/` — Buy a request bundle (no auth required). Returns a 402 challenge advertising `stripe` (Shared Payment Token, card/wallet, synchronous) and `tempo` (USDC on Tempo, asynchronous) settlement methods. Pay with either and the response carries your API key.

## Supported newsletter platforms

The Reletter index covers five platforms. The `platform` field on every publication is one of: `substack`, `linkedin_newsletter`, `ghost`, `beehiiv`, `kit`. Filter by platform in search with `platforms:any:substack-beehiiv-kit` etc.