Create a segment
const url = 'https://api.tryletterhead.com/api/v3/contacts/segments?api=true';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"Engaged opens - last 30 days","description":"Contacts who opened in the last 30 days","criteria":{"matchMode":"all","conditions":[{"type":"tag","operator":"has","value":"engaged"}],"suppressionSegmentIds":[]},"channelSlugs":[]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.tryletterhead.com/api/v3/contacts/segments?api=true' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Engaged opens - last 30 days", "description": "Contacts who opened in the last 30 days", "criteria": { "matchMode": "all", "conditions": [ { "type": "tag", "operator": "has", "value": "engaged" } ], "suppressionSegmentIds": [] }, "channelSlugs": [] }'Creates a company-level contact segment. A segment is a saved audience query; membership is never materialized — the criteria are evaluated live.
This is a company-level (v3) write. Authenticate with a company API key as a Bearer token.
Response
201 Created. The persisted segment is returned under items (see List segments for the segment shape). A duplicate name returns 409.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Required. Set to true.
Request Body required
Section titled “Request Body required ”object
Segment name. Max 255 chars. Must be unique within the company.
Free-text description. Max 500 chars.
The saved query.
object
all (AND the conditions) or any (OR the conditions).
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 to scope the segment to. Omit or send an empty array to make it available on every channel.
Example
{ "name": "Engaged opens - last 30 days", "description": "Contacts who opened in the last 30 days", "criteria": { "matchMode": "all", "conditions": [ { "type": "tag", "operator": "has", "value": "engaged" } ], "suppressionSegmentIds": [] }, "channelSlugs": []}Responses
Section titled “ Responses ”201 Created
object
object
The segment’s identifier.
The segment’s name (unique per company).
The segment’s description.
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": 9, "name": "Engaged opens - last 30 days", "description": "Contacts who opened in the last 30 days", "criteria": { "matchMode": "all", "conditions": [ { "type": "tag", "operator": "has", "value": "engaged" } ], "suppressionSegmentIds": [] }, "channelSlugs": [], "createdAt": "2026-06-20 12:00:00", "updatedAt": "2026-06-20 12:00:00" }, "message": "Segment created.", "total": 1}Still can’t find what you need? Contact support.