List all letters

GET

/api/v3/letters

const url = 'https://api.tryletterhead.com/api/v3/letters?api=true&status=1&page=1&limit=12&orderBy=updated_at&asc=false&allChannels=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/letters?api=true&status=1&page=1&limit=12&orderBy=updated_at&asc=false&allChannels=true' \
  --header 'Authorization: Bearer <token>'

List the company’s letters, most-recently-updated first, with pagination and filtering.

This returns letters from across your entire company, rather than from a single newsletter.

Channel scope. With no channel filter, this endpoint returns the company’s templates, which are the only types of letter that are available across a company. To list real published/sent newsletters — which live on the company’s individual channels — pass one of:

allChannels=true — return letters across every channel the company owns.
channels[] — a repeatable array of channel slugs to restrict results to specific channels.

If both are supplied, the explicit channels[] list is honored.

Response. A paginated envelope: items holds the array of letters and total is the count of matching letters (there is no message field on this endpoint). Each letter includes fields such as uniqueId, title, subtitle, publicationDate, publicationStatus, segmentName, channelSlug, and channelName — the full letter object has many more fields than shown here. To fetch a single letter’s fully rendered HTML (emailTemplate), take a uniqueId from this list and call Retrieve a letter by its uniqueId.

Tip. Combine status, keyword, orderBy, and paging to page through large audiences efficiently — assume the list can be long and request one page at a time.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

When true, tells the endpoint you are authenticating with a company API key (generated under a company’s administrative settings) rather than a logged-in user session. For API integrations you will almost always set this to true.

status

string

Example

(optional) Filter by publication status code. Common values: 0 draft, 1 published, 2 scheduled, 6 any (default), 9 configured template. Omit, or pass 6, to return letters of every status.

page

string

Example

(optional) 1-based page number. Defaults to 1.

limit

string

Example

(optional) Results per page, 1–100. Defaults to 12.

orderBy

string

Example

updated_at

(optional) Column to sort by, e.g. updated_at (default) or publication_date.

asc

string

Example

false

(optional) Sort direction. true for ascending, false (default) for descending.

keyword

string

(optional) Free-text search across letter title/subject.

templates

string

(optional) Repeatable templates[] array to restrict results to specific template types. Leave off to include all.

channels

string

(optional) Repeatable channels[] array of channel slugs. When supplied, the endpoint returns real letters across those specific channels (published/sent newsletters, not the company’s virtual-channel templates). Combine with status, keyword, and paging as usual.

allChannels

string

Example

true

(optional) When true, returns real letters across every channel the company owns (published/sent newsletters, not the company’s virtual-channel templates). Mutually redundant with channels[] — if both are given, the explicit channel list is honored. Accepts true/false (defaults to false).

Responses

200

List all letters

application/json

object

items

Array<object>

Shown here are the fields most integrators use — the full letter object carries many more.

object

uniqueId

string

title

string

subtitle

string

publicationDate

string

publicationStatus

integer

segmentName

string

channelSlug

string

channelName

string

updatedAt

string

total

integer

Example

{
  "items": [
    {
      "uniqueId": "ludctamgd6",
      "title": "Who doesn't love a good movie?",
      "subtitle": "A new exhibition, two openings, and a closer look at this season's residency.",
      "publicationDate": "2026-05-06 05:53:05",
      "publicationStatus": 1,
      "segmentName": "Entire audience",
      "channelSlug": "an-example-channel",
      "channelName": "An Example Channel",
      "updatedAt": "2026-05-06 05:53:05"
    },
    {
      "uniqueId": "9plmk2xqta",
      "title": "This week at the museum",
      "subtitle": "Members-only hours return.",
      "publicationDate": "2026-04-29 05:53:05",
      "publicationStatus": 1,
      "segmentName": "Members",
      "channelSlug": "an-example-channel",
      "channelName": "An Example Channel",
      "updatedAt": "2026-04-29 05:53:05"
    }
  ],
  "total": 2
}

Still can’t find what you need? Contact support.