List system segments

GET

/api/v3/contacts/segments/system

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

Lists Letterhead’s built-in, reserved system segments — Loyalists, New & Engaged, Casual, Fading, Ghosts, Single Newsletter, Everyone but Ghosts, and (where enabled for your account) Everyone but Ghosts (60 days) — each with the reserved integer id it sends to. Pass that id as segment when sending a letter to target one without hard-coding a number copied out of the app.

A separate, read-only listing from List segments above: a system segment is never created, updated, or deleted, and this endpoint leaves GET /api/v3/contacts/segments unchanged.

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

Required. Set to true.

channel

string

A channel identifier (slug) to validate against your account. The listing itself is always company-wide — passing a channel doesn’t narrow it, and an invalid one returns an error.

Responses

200

200 OK

application/json

object

items

Array<object>

object

The segment’s reserved identifier. Pass this as segment when sending.

integer

key

A stable, human-legible identifier for the segment (e.g. loyalists, everyoneButGhosts). Not an alternate send-time identifier — sending still requires the numeric id.

string

name

The segment’s display name (e.g. “Loyalists”, “Everyone but Ghosts”).

string

message

string

total

integer

Example

{
  "items": [
    {
      "id": 100001,
      "key": "loyalists",
      "name": "Loyalists"
    },
    {
      "id": 100002,
      "key": "newEngaged",
      "name": "New & Engaged"
    },
    {
      "id": 100003,
      "key": "casual",
      "name": "Casual"
    },
    {
      "id": 100004,
      "key": "fading",
      "name": "Fading"
    },
    {
      "id": 100005,
      "key": "ghosts",
      "name": "Ghosts"
    },
    {
      "id": 100006,
      "key": "singleNewsletter",
      "name": "Single Newsletter"
    },
    {
      "id": 100007,
      "key": "everyoneButGhosts",
      "name": "Everyone but Ghosts"
    }
  ],
  "message": "System segments retrieved.",
  "total": 7
}

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