Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Preview segment members

POST
/api/v3/contacts/segments/{segmentId}/preview
 
curl --request POST \
  --url 'https://api.tryletterhead.com/api/v3/contacts/segments/1/preview?api=true' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "pageSize": 1, "searchAfter": "example", "channel": "example" }'

Previews the contacts that currently match a segment’s criteria, evaluated live. Results are cursor-paginated with searchAfter.

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

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
segmentId
required
integer

The segment’s identifier.

Query Parameters

Section titled “Query Parameters ”
api
required
boolean

Required. Set to true.

Request Body

Section titled “Request Body ”
Media type application/json
object
pageSize

Page size, 1–100. Defaults to 25.

integer
searchAfter

Opaque cursor from the previous page’s searchAfter. Omit or send null for the first page.

string
channel

Narrow the preview to contacts subscribed to the given channel identifier (slug). Omit for the full company audience.

string
Example generated
{
  "pageSize": 1,
  "searchAfter": "example",
  "channel": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

200 OK

Media type application/json
object
items
object
contacts

The matched contacts for this page.

Array<object>
object
email
string
firstName
string
lastName
string
tags
Array<string>
customFields
object
__lh.engagementRefreshedAt
string
__lh.mailboxProvider
string
__lh.roleAddress
boolean
age
integer
referralSource
string
lastOpenDate
string
subscriptions

The channels this contact is subscribed to. A subscription whose channel was since deleted is dropped rather than shown as a placeholder.

Array<object>
object
channel
object
slug
string
name
string
status

The subscription status, 0-7.

integer
createdAt
string
updatedAt
string
endpoints
Array<object>
object
channelConsents
Array<object>
object
consents
Array<object>
object
createdAt
string
updatedAt
string
searchAfter

Opaque cursor for the next page — pass it back as searchAfter.

string
nullable
totalRelation

Whether the top-level total is exact (eq) or a lower bound (gte).

string
message
string
total
integer
Example 
{
  "items": {
    "contacts": [
      {
        "email": "[email protected]",
        "firstName": "Avery",
        "lastName": "Chen",
        "tags": [
          "engaged-readers"
        ],
        "customFields": {
          "__lh.engagementRefreshedAt": "2026-06-14T04:20:28+00:00",
          "__lh.mailboxProvider": "gmail",
          "__lh.roleAddress": false,
          "age": 36,
          "referralSource": "Archive page",
          "lastOpenDate": "2026-06-12 06:29:04"
        },
        "subscriptions": [
          {
            "channel": {
              "slug": "the-daily",
              "name": "The Daily"
            },
            "status": 1,
            "createdAt": "2026-05-23T11:43:15+00:00",
            "updatedAt": "2026-05-23T11:43:15+00:00"
          }
        ],
        "endpoints": [],
        "channelConsents": [],
        "consents": [],
        "createdAt": "2026-05-23T11:43:15+00:00",
        "updatedAt": "2026-06-18T09:12:04+00:00"
      },
      {
        "email": "[email protected]",
        "firstName": "Jordan",
        "lastName": "Reyes",
        "tags": [
          "engaged-readers",
          "the-north"
        ],
        "customFields": {
          "__lh.engagementRefreshedAt": "2026-06-14T04:20:28+00:00",
          "__lh.mailboxProvider": "other",
          "__lh.roleAddress": false,
          "age": 42,
          "referralSource": "Embedded subscription box",
          "lastOpenDate": "2026-06-13 18:02:11"
        },
        "subscriptions": [
          {
            "channel": {
              "slug": "the-daily",
              "name": "The Daily"
            },
            "status": 1,
            "createdAt": "2026-05-23T11:43:15+00:00",
            "updatedAt": "2026-05-23T11:43:15+00:00"
          },
          {
            "channel": {
              "slug": "weekend-reads",
              "name": "Weekend Reads"
            },
            "status": 1,
            "createdAt": "2026-06-01T09:00:00+00:00",
            "updatedAt": "2026-06-01T09:00:00+00:00"
          }
        ],
        "endpoints": [],
        "channelConsents": [],
        "consents": [],
        "createdAt": "2026-05-23T11:43:15+00:00",
        "updatedAt": "2026-06-18T09:12:04+00:00"
      }
    ]
  },
  "message": "Segment preview retrieved.",
  "total": 1284
}

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