List segments

GET

/api/v3/contacts/segments

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/contacts/segments?api=true' \
  --header 'Authorization: Bearer <token>'

• Production

Lists the company’s contact segments. Segments are saved audience queries and evaluated live — distinct from the deprecated GET /api/v3/audience/segments, which returns legacy per-channel segments.

This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.

Authorizations

• bearerAuth

Parameters

Query Parameters

api

required

boolean

Set to true.

channel

string

Narrow the listing to segments assigned to the given channel identifier (slug), plus segments available on every channel. Omit for the full company-wide listing.

Responses

200

200 OK

Media type application/json

object

items

Array<object>

object

id

The segment’s identifier.

integer

name

The segment’s name (unique per company).

string

description

The segment’s description.

string

criteria

The saved query: matchMode (all/any), conditions[], and suppressionSegmentIds[].

object

matchMode

string

conditions

Array<object>

object

type

string

customFieldKey

string

operator

string

value

string

suppressionSegmentIds

Array<object>

object

channelSlugs

Channels the segment is scoped to. An empty array means it is available on every channel.

Array<string>

createdAt

Creation timestamp.

string

updatedAt

Last-updated timestamp.

string

message

string

total

integer

Example

{
  "items": [
    {
      "id": 5,
      "name": "Readers over 30",
      "description": "Contacts whose age custom field is over 30",
      "criteria": {
        "matchMode": "all",
        "conditions": [
          {
            "type": "customField",
            "customFieldKey": "age",
            "operator": ">",
            "value": "30"
          }
        ],
        "suppressionSegmentIds": []
      },
      "channelSlugs": [
        "the-daily",
        "weekend-reads",
        "product-updates"
      ],
      "createdAt": "2026-05-20 17:48:15",
      "updatedAt": "2026-05-20 17:48:15"
    },
    {
      "id": 7,
      "name": "Highly engaged readers",
      "description": "Opened at least one letter in the last 30 days",
      "criteria": {
        "matchMode": "any",
        "conditions": [
          {
            "type": "tag",
            "operator": "has",
            "value": "engaged-readers"
          }
        ],
        "suppressionSegmentIds": [
          12
        ]
      },
      "channelSlugs": [
        "the-daily"
      ],
      "createdAt": "2026-06-01 09:14:02",
      "updatedAt": "2026-06-11 16:30:47"
    }
  ],
  "message": "Segments retrieved.",
  "total": 2
}