List segments
const url = 'https://api.tryletterhead.com/api/v3/contacts/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/contacts/segments?api=true' \ --header 'Authorization: Bearer <token>'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
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Set to true.
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
Section titled “ Responses ”200 OK
object
object
The segment’s identifier.
The segment’s name (unique per company).
The segment’s description.
The saved query: matchMode (all/any), conditions[], and suppressionSegmentIds[].
object
At least one condition. The shape of each depends on its type — see the schemas below.
object
The custom field’s key (see List custom field definitions).
=, >, <, >=, <=, inLastDays, notInLastDays, or isEmpty.
Comparison value. Omitted for the isEmpty operator, which carries no value. For inLastDays/notInLastDays, an integer number of days as a string.
Matches contacts by tag. Flags: none — on for everyone.
object
has or notHas.
The tag name.
Matches contacts by their subscription to a channel. Flags: none — on for everyone.
object
The channel to match a subscription on.
Optional subscription status to match, 0-7. Omit to match any status.
Free-text match against a contact’s email, first name, and last name. Flags: none — on for everyone.
object
The text to search for.
Matches readers who opened one specific edition — the one-click shortcut from an edition’s own metrics. Flags: engagementSegments (off for everyone as of this writing).
object
The edition’s unique identifier.
Matches readers who clicked a specific link in one specific edition — the one-click shortcut. Flags: engagementSegments (off for everyone as of this writing).
object
The edition’s unique identifier.
The clicked URL.
Matches readers whose opens over a recently-published window, or a specific set of editions, meet a threshold — built directly in the segment builder rather than from a single edition’s metrics. Flags: segmentBuilderEngagementWindow (off for everyone as of this writing).
object
Channel identifier (slug) the engagement is evaluated against.
recently_published or specific_emails.
Number of recently-published editions to consider, 1-50. Used only with mode=recently_published.
Specific edition unique identifiers to consider. Used only with mode=specific_emails.
Minimum number of matching editions required.
Optional maximum number of matching editions. Omit for no upper bound.
Matches readers whose clicks over a recently-published window, or a specific set of editions, meet a threshold. Flags: segmentBuilderEngagementWindow (off for everyone as of this writing).
object
Channel identifier (slug) the engagement is evaluated against.
recently_published or specific_emails.
Number of recently-published editions to consider, 1-50. Used only with mode=recently_published.
Specific edition unique identifiers to consider. Used only with mode=specific_emails.
Minimum number of matching editions required.
Optional maximum number of matching editions. Omit for no upper bound.
Narrow to these specific link URLs. Omit or leave empty to match a click on any link.
Matches contacts within a radius of a location. Flags: contactGeolocationSegments (off for everyone as of this writing).
object
Center latitude, -90 to 90.
Center longitude, -180 to 180.
Radius in miles. Must be greater than zero.
Matches readers who chose a specific poll answer, across every edition the poll appeared in. Flags: engagementSegments gates the condition type itself (off for everyone as of this writing); resolving voters from a send through a non-Letterhead ESP additionally needs pollSegmentsAllEsps (also off for everyone as of this writing).
object
The poll’s identifier.
The chosen option’s identifier.
IDs of other segments (same company) whose members are excluded from this segment’s audience.
Channels the segment is scoped to. An empty array means it is available on every channel.
Creation timestamp.
Last-updated timestamp.
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}Still can’t find what you need? Contact support.