MCP tools — Segments
Five tools to manage saved audience filters with rule definitions.
Segments are saved audience filters — a JSON rule definition that resolves to a contact set on demand. Useful as broadcast targets and as triggers for sequences/flows.
| Tool | Annotation | Purpose |
|---|---|---|
list_segments |
IsReadOnly, IsIdempotent |
Paginate with cached counts |
get_segment |
IsReadOnly, IsIdempotent |
Fetch + refreshed count |
create_segment |
IsDestructive(false) |
New segment from rules |
update_segment |
IsDestructive(false), IsIdempotent |
Rename, redefine rules |
delete_segment |
IsDestructive |
Delete (contacts untouched) |
list_segments
List segments (saved audience filters) for the workspace, with their cached contact counts.
Returns {data: Segment[], meta: {…}}. Counts are cached and may lag a few minutes behind reality — call get_segment for a fresh count.
get_segment
Get one segment with its full rule definition and refreshed contact count.
| Input | Type |
|---|---|
id |
UUID |
Triggers a count refresh, then returns the segment plus the fresh contacts_count.
create_segment
Create a new segment from a rule definition. The contact count is computed immediately.
| Input | Type | Notes |
|---|---|---|
name |
string | required |
description |
string | optional |
rules |
object | required — JSON shape |
The rules object follows the segment DSL used by the dashboard: a tree of conditions with and/or combinators and predicates on tags, last_message_at, created_at, metadata.*, etc. The fastest way to author rules is the dashboard's segment builder, then call get_segment to copy the resulting JSON.
update_segment
Update a segment's name, description, or rules. Refreshes the contact count after rules changes.
delete_segment
Permanently delete a segment. Does not delete the contacts it referenced.