Get a segment
const url = 'https://api.tryletterhead.com/api/v3/contacts/segments/1?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/1?api=true' \ --header 'Authorization: Bearer <token>'Retrieves a single company-level contact segment by its ID.
This is a company-level (v3) read. Authenticate with a company API key as a Bearer token.
Response
The segment is returned under items (see List segments for the segment shape). An unknown ID (or one owned by another company) returns 404.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The segment’s identifier. This is the numeric id returned by List segments — not a UUID.
Query Parameters
Section titled “Query Parameters ”Required. Set to true.
Responses
Section titled “ Responses ”200 OK
object
object
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.
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" }, "message": "Segment retrieved.", "total": 1}Still can’t find what you need? Contact support.