Introduction
The Letterby REST API for offers, agreements, subscribers, payouts and balance.
The Letterby API lets you manage offers, accept offers for your newsletter, and read subscribers, payouts and balance from your own code.
https://api.letterby.com/v1Requests and responses are JSON. Every request needs an API key.
Make your first request
Create a key. In Letterby open Settings, then Integrations, then Create key. Copy it now. It is shown once.
Call the API.
curl https://api.letterby.com/v1/me \
-H "Authorization: Bearer $LETTERBY_API_KEY"Read the response.
{
"object": "account",
"team": {
"id": "019aโฆ",
"name": "Acme Media",
"created_at": "2026-09-14T09:12:03.000Z"
},
"api_key": {
"id": "019aโฆ",
"name": "Backend",
"scope": "full",
"last_used_at": null,
"created_at": "2026-11-01T08:00:00.000Z"
}
}How the API is organised
A key belongs to one team. Most resources sit under one of that team's publications.
| Resource | Path | Use it to |
|---|---|---|
| Account | /v1/me | Check which team and key you are using. |
| Publications | /v1/publications | List your newsletters and get their ids. |
| Offers | /v1/publications/{pub_id}/offers | Create and manage the offers you pay for. |
| Directory | /v1/directory/offers | Find offers your newsletter can promote. |
| Agreements | /v1/publications/{pub_id}/agreements | Accept offers, get tracking links, read subscribers. |
| Payouts | /v1/payouts | Read what you were paid. |
| Balance | /v1/balance | Read the funds available for your offers. |
| Webhooks | /v1/webhooks | Get notified when something happens. |
Conventions
| Topic | Rule |
|---|---|
| Money | Integer cents with a currency field. Only usd today. |
| Dates | ISO 8601 in UTC. |
| IDs | UUIDs. |
| Request body | JSON, up to 32 KB. |
| Timeout | A request that takes longer than 10 seconds returns 500. |
| Request id | Every response has an X-Request-Id header. Quote it to support. |
| Version | Every response has API-Version: v1. |
| Browsers | CORS is open, but a key in browser code is public. Call the API from a server. |