List newsletter-level segments (deprecated)

Deprecated

GET

/api/v3/audience/segments

const url = 'https://api.tryletterhead.com/api/v3/audience/segments?api=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/audience/segments?api=true' \
  --header 'Authorization: Bearer <token>'

This endpoint is deprecated in favor of the company-wide Contacts endpoints, which do the same job with more flexibility and at a larger scale. It is documented here for accounts still calling it; use the Contacts endpoints for anything new.

Replaced by GET /api/v3/contacts/segments. Some longer-standing accounts still see a newsletter-level segment list here. Dynamic segments that Letterhead maintains for you are not included.

Authorizations

bearerAuth

Parameters

Query Parameters

api

required

boolean

Required. Set to true.

name

string

Narrow the listing to segments whose name contains this text.

channel

string

Narrow the listing to segments assigned to the given channel identifier (slug).

page

integer

1-based page number. Minimum 1. Defaults to 1.

itemsPerPage

integer

Segments per page. Minimum 1, maximum 100. Defaults to 20.

Responses

200

200 OK

application/json

object

items

Array<object>

object

uniqueId

The segment’s identifier. Legacy behavior — unlike every other uniqueId in this spec, this deprecated endpoint’s field name carries the raw internal numeric ID (ChannelSegments::convertToPublicArray()), not a non-sequential unique identifier.

integer

channel

The channel identifier (slug) this segment belongs to.

string

name

The segment’s name.

string

criteria

The legacy per-segment criteria rows. Unlike the company-wide segments’ conditions[], this shape isn’t standardized across condition kinds.

Array<object>

object

attribute

string

category

string

operator

string

value

string

isOrBoolean

When true, a contact matches if any criteria row matches (OR). When false, every row must match (AND).

boolean

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": [
    {
      "uniqueId": 22,
      "channel": "the-daily",
      "name": "Engaged readers",
      "criteria": [
        {
          "attribute": "opens",
          "category": "engagement",
          "operator": ">",
          "value": "5"
        }
      ],
      "isOrBoolean": false,
      "createdAt": "2026-03-11 08:20:00",
      "updatedAt": "2026-03-11 08:20:00"
    }
  ],
  "message": "",
  "total": 1
}

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