Update a segment
const url = 'https://api.tryletterhead.com/api/v3/contacts/segments/1?api=true';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"Engaged opens - last 60 days","description":"Updated window","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 PUT \ --url 'https://api.tryletterhead.com/api/v3/contacts/segments/1?api=true' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Engaged opens - last 60 days", "description": "Updated window", "criteria": { "matchMode": "all", "conditions": [ { "type": "tag", "operator": "has", "value": "engaged" } ], "suppressionSegmentIds": [] }, "channelSlugs": [] }'Updates a company-level contact segment. This is a partial update — every field is optional; only the fields you send are changed, and omitted fields keep their existing values.
This is a company-level (v3) write. Authenticate with a company API key as a Bearer token.
Response
The updated segment is returned under items. An unknown ID returns 404; a duplicate name returns 409.
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.
Request Body required
Section titled “Request Body required ”object
Segment name. Max 255 chars. Unique within the company.
Free-text description. Max 500 chars.
The saved query — same shape as Create a segment.
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 to scope the segment to. An empty array means available on every channel.
Example
{ "name": "Engaged opens - last 60 days", "description": "Updated window", "criteria": { "matchMode": "all", "conditions": [ { "type": "tag", "operator": "has", "value": "engaged" } ], "suppressionSegmentIds": [] }, "channelSlugs": []}Responses
Section titled “ Responses ”200 OK
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": 5, "name": "Engaged opens - last 60 days", "description": "Updated window", "criteria": { "matchMode": "all", "conditions": [ { "type": "tag", "operator": "has", "value": "engaged" } ], "suppressionSegmentIds": [] }, "channelSlugs": [], "createdAt": "2026-05-20 17:48:15", "updatedAt": "2026-06-20 12:05:00" }, "message": "Segment updated.", "total": 1}Still can’t find what you need? Contact support.