Letterby Docs

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/v1

Requests 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.

ResourcePathUse it to
Account/v1/meCheck which team and key you are using.
Publications/v1/publicationsList your newsletters and get their ids.
Offers/v1/publications/{pub_id}/offersCreate and manage the offers you pay for.
Directory/v1/directory/offersFind offers your newsletter can promote.
Agreements/v1/publications/{pub_id}/agreementsAccept offers, get tracking links, read subscribers.
Payouts/v1/payoutsRead what you were paid.
Balance/v1/balanceRead the funds available for your offers.
Webhooks/v1/webhooksGet notified when something happens.

Conventions

TopicRule
MoneyInteger cents with a currency field. Only usd today.
DatesISO 8601 in UTC.
IDsUUIDs.
Request bodyJSON, up to 32 KB.
TimeoutA request that takes longer than 10 seconds returns 500.
Request idEvery response has an X-Request-Id header. Quote it to support.
VersionEvery response has API-Version: v1.
BrowsersCORS is open, but a key in browser code is public. Call the API from a server.

Next

On this page