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 the envelope carries the total/paging metadata. Each letter includes fields such as uniqueId, title, subject, subtitle, publicationDate, publicationStatus, segmentName, and channel. 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>

object

uniqueId

string

title

string

subject

string

subtitle

string

publicationDate

string

publicationStatus

integer

segmentName

string

channel

string

updatedAt

string

message

string

total

integer

Example

{
  "items": [
    {
      "uniqueId": "ludctamgd6",
      "title": "Who doesn't love a good movie?",
      "subject": "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",
      "channel": "an-example-channel",
      "updatedAt": "2026-05-06 05:53:05"
    },
    {
      "uniqueId": "9plmk2xqta",
      "title": "This week at the museum",
      "subject": "This week at the museum",
      "subtitle": "Members-only hours return.",
      "publicationDate": "2026-04-29 05:53:05",
      "publicationStatus": 1,
      "segmentName": "Members",
      "channel": "an-example-channel",
      "updatedAt": "2026-04-29 05:53:05"
    }
  ],
  "message": "",
  "total": 2
}

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