Kenso MCP tools

Segments segments

Campaign segments. preview counts the leads that match criteria and returns the filter catalog too, so call it directly. criteria uses the camelCase filter_criteria keys of create, such as titles, industries, seniorityLevels and leadQualityScore {min, max}. update replaces the whole filter_criteria: send every current key from get plus the change, as {"titles": ["CEO"], "profileCountries": ["United States"]}. process_filters assigns a segment's contacts from its saved filters: call it with segment_id, it reads the filters itself. Only a manual segment holds filter_criteria: update refuses it on an ai or ab_test segment, and an AI campaign's Default is ai. Narrow such a campaign with a new manual segment and process_filters; the leads it does not match stay in Default.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through segments_read and changes through segments_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.

Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.

Operations: activate, apply-provider-track-to-all, blocklist-entries-bulk-delete, create, deactivate, delete, get, get-filter-options, get-provider-tracks, get-sender-routing, get-version, list, list-versions, preview, replace-sender-routing, restore-version, save-version, set-provider-track, update, process_filters

activate

Write. POST https://api.ken.so/v1/segments/{segmentId}/activate

Path: segmentId

Activate a segment. Idempotent when the segment is already active. Requires Campaigns edit.

POST /api/v1/segments/{segmentId}/activate. Public. Sends Ken-Version 1.1.

apply-provider-track-to-all

Write. POST https://api.ken.so/v1/segments/{segmentId}/provider-tracks/{track}/apply-to-all

Path: segmentId, track

Make every provider track of a segment send one track's copy. Requires Campaigns edit.

POST /api/v1/segments/{segmentId}/provider-tracks/{track}/apply-to-all. Public.
Sends Ken-Version 1.1. client_id is sent as X-Ken-Workspace-Id. Needs the workspace's
provider_tracks flag.
track: google, microsoft or other (everyone else).
If that track has its own sequence, the segment's email sequence is replaced with it
(with every check a sequence save runs) and every track's own copy is dropped, so all
three tracks share one sequence again. If it already shares the segment's sequence,
only the other tracks' own copies are dropped. This overwrites the other tracks'
copy: call it only when the user asked for the same copy on all tracks.
Returns the three tracks as get-provider-tracks does.
Errors (validation_failed detail): feature_disabled, invalid_track, no_sequence, or a
sequence save's own codes; nothing is dropped when the save is refused.

blocklist-entries-bulk-delete

Write. POST https://api.ken.so/v1/blocklist-entries/bulk-delete

Body (json): ids array

Remove up to 1,000 blocklist entries in one call. Returns succeeded ids and failed {id, error}. To undo a bulk add, skip its claimed rows.

POST /api/v1/blocklist-entries/bulk-delete. Public. Sends Ken-Version 1.1.
Requires the `workspace_settings` permission. entry_ids are blocklist entry ids from
lists(operation="blocklist-entries-list") or a bulk add's succeeded rows.
To undo a bulk add, pass only the succeeded ids without claimed: true. A
claimed entry was blocked before the add (by a customer account or a
rule), so deleting it unblocks a domain the person never added, and a
customer entry does not come back on its own.
An id already removed or outside the workspace counts as succeeded.
An own-domain entry fails with invalid_state, and so does a rule entry
while the blocklist rules are on: change the rules instead.

create

Write. POST https://api.ken.so/v1/campaigns/{campaignId}/segments

Path: campaignId

Body (json): abTestPercentage integer, description string, filterCriteria object, name string, segmentationType string, sortOrder integer

Create a segment on a campaign in the current workspace. Returns 201 and Location. Requires Campaigns edit.

POST /api/v1/campaigns/{campaignId}/segments. Public. Sends Ken-Version 1.1.

segmentation_type is manual, ai, or ab_test. ab_test_percentage is 0 through 100.
filter_criteria is the campaign segment filter object. Its keys are camelCase:
fullName, titles, excludeTitles, lastJobTitle, headlines, excludeHeadlines,
summaryContains, seniorityLevels, excludeSeniorityLevels, functions,
excludeFunctions, employmentTypes, isDecisionMaker, changedJobRecently,
yearsOfExperience, yearsInCurrentRole, yearsInCurrentCompany, profileCountries,
excludeProfileCountries, profileState, profileCity, skillsContains,
certificationsContains, languages, emailValidity, emailProviders,
excludeEmailProviders, isPersonalEmail, hasLinkedInUrl, hasPhone, hasValidPhone,
companyNames, excludeCompanyNames, companyDomainContains,
companyDescriptionContains, companySpecialitiesContains, industries,
excludeIndustries, companyHeadcount, companyFollowers, companyFoundedYear,
companyTypes, lastFundingRounds, totalFunding, technologies, excludeTechnologies,
companyHqCountries, excludeCompanyHqCountries, companyHqState, companyHqCity,
doNotContact, createdAt, totalClicks, leadQualityScore, behaviorTags,
behaviorTagsExclude, aiVariableFilters, customVariableFilters. Keys match case-insensitively (Titles works, seniority_levels
does not) and are sent in the camelCase spelling above. An unknown key, or one field named twice, is refused before
any call, naming it.
segments(operation="get-filter-options") lists the valid values of the list filters.

deactivate

Write. POST https://api.ken.so/v1/segments/{segmentId}/deactivate

Path: segmentId

Deactivate a segment. Idempotent when the segment is already inactive. Requires Campaigns edit.

POST /api/v1/segments/{segmentId}/deactivate. Public. Sends Ken-Version 1.1.

delete

Write. DELETE https://api.ken.so/v1/segments/{segmentId}

Path: segmentId

Soft-delete a segment. Returns 204. Requires Campaigns edit access (owners, admins and editors by default).

DELETE /api/v1/segments/{segmentId}. Public. Sends Ken-Version 1.1.

get

Read. GET https://api.ken.so/v1/segments/{segmentId}

Path: segmentId

Return one segment in the current workspace. A missing or cross-workspace id is not_found.

GET /api/v1/segments/{segmentId}. Public. Sends Ken-Version 1.1.

get-filter-options

Read. GET https://api.ken.so/v1/segments/filter-options

Read the segment filter catalog: the valid values of each filter, no campaign needed. Public. Requires Campaigns view.

GET /api/v1/segments/filter-options. Public. Sends Ken-Version 1.1. client_id is sent as
X-Ken-Workspace-Id. Needs Campaigns view. data holds seniorityLevels, functions, industries,
companyTypes, employmentTypes, lastFundingRounds, technologies, emailValidity, emailProviders
and languages, each a list of {value, label, category?}: the object
segments(operation="preview") returns as data.filterOptions. Use the values in criteria
for segments(operation="preview"), create and update.

get-provider-tracks

Read. GET https://api.ken.so/v1/segments/{segmentId}/provider-tracks

Path: segmentId

Get a segment's provider tracks: google, microsoft and other, with lead counts. Requires Campaigns view.

GET /api/v1/segments/{segmentId}/provider-tracks. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Needs the workspace's provider_tracks flag
(else validation_failed with detail feature_disabled).
Format follows the recipient's mail provider. Inside one campaign, leads split into
provider tracks: Google, Microsoft, Everyone else. A recipient on Google (Google
Workspace or gmail.com) gets plain text. A recipient on Microsoft (Microsoft 365 or
outlook.com) gets the email as written, HTML included.
Per track: leadCount, sequenceSegmentId (read or replace that track's copy with the
segment-email-sequences operations on this id), hasOwnSequence (false while the track
shares the segment's sequence), sameAs (the tracks sharing its copy), sendsPlainText.
enabled false means the campaign is not on provider tracks and sends as before.
A contact whose provider is not known yet counts under google.

get-sender-routing

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/sender-routing

Path: campaignId

Get a campaign's sender routing: its inbox mode, rules, capacity and warnings. Requires Campaigns view.

GET /api/v1/campaigns/{campaignId}/sender-routing. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Needs the workspace's sender_routing flag
(else validation_failed with detail feature_disabled).
allInboxes: true means inboxes connected later join the campaign.
Each rule sends the first email to prospects on its provider (a gateway rule wins
over a mailbox provider rule) only from its domains and inboxIds; everyoneElse is
the inboxes no rule claims. Per group: sendableInboxCount, dailyCapacity, leadCount.
warnings: rule_no_inbox, everyone_else_no_inbox, rule_slow (days over 5).

get-version

Read. GET https://api.ken.so/v1/segments/{segmentId}/versions/{versionId}

Path: segmentId, versionId

Return one segment version and its snapshot. Snapshot segmentationType and status are lowercase snake_case.

GET /api/v1/segments/{segmentId}/versions/{versionId}. Public. Sends Ken-Version 1.1.
Requires Campaigns view. A segment outside the workspace is not_found.

list

Read. GET https://api.ken.so/v1/campaigns/{campaignId}/segments

Path: campaignId

Query: cursor string, includeMetrics boolean, isActive boolean, limit integer, q string

List segments of a campaign in the current workspace. q matches the name. is_active filters active or inactive segments. include_metrics=false skips the contact counts: faster when only ids and names are needed.

GET /api/v1/campaigns/{campaignId}/segments. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Ordered by id. include_metrics defaults to true;
false omits contactCount, rawContactCount and readyContactCount.

list-versions

Read. GET https://api.ken.so/v1/segments/{segmentId}/versions

Path: segmentId

Query: cursor string, limit integer

List saved versions of a segment, newest first. limit is 1 to 100. Omit it for 20. Requires Campaigns view.

GET /api/v1/segments/{segmentId}/versions. Public. Sends Ken-Version 1.1.

preview

Read. POST https://api.ken.so/v1/campaigns/{campaignId}/segments/preview

Path: campaignId

Query: segmentId integer

Body (json): aiVariableFilters array, behaviorTags array, behaviorTagsExclude array, certificationsContains string, changedJobRecently boolean, companyDescriptionContains string, companyDomainContains string, companyFollowers object, companyFoundedYear object, companyHeadcount object, companyHqCity string, companyHqCountries array, companyHqState string, companyNames array, companySpecialitiesContains string, companyTypes array, createdAt object, customVariableFilters array, doNotContact boolean, emailProviders array, emailValidity array, employmentTypes array, excludeCompanyHqCountries array, excludeCompanyNames array, excludeEmailProviders array, excludeFunctions array, excludeHeadlines array, excludeIndustries array, excludeProfileCountries array, excludeSeniorityLevels array, excludeTechnologies array, excludeTitles array, fullName object, functions array, hasLinkedInUrl boolean, hasPhone boolean, hasValidPhone boolean, headlines array, industries array, isDecisionMaker boolean, isPersonalEmail boolean, languages array, lastFundingRounds array, lastJobTitle object, leadQualityScore object, profileCity string, profileCountries array, profileState string, seniorityLevels array, skillsContains string, summaryContains string, technologies array, titles array, totalClicks object, totalFunding object, yearsInCurrentCompany object, yearsInCurrentRole object, yearsOfExperience object

Preview a segment filter, or the filter catalog when criteria is omitted. The catalog returns the same preview shape. Requires Campaigns view.

POST /api/v1/campaigns/{campaignId}/segments/preview. Public. Sends Ken-Version 1.1.
Omit criteria to read the catalog only. A body, including an empty object, runs the match preview.
Both return matchingCount, sampleContacts, and filterOptions. segment_id scopes a match preview.
criteria takes the filter_criteria keys of segments(operation="create"): they match
case-insensitively and are sent camelCased, and an unknown key is refused before the call.
Sample emailValidity is lowercase snake_case.
segments(operation="get-filter-options") reads the same catalog without a campaign.

replace-sender-routing

Write. PUT https://api.ken.so/v1/campaigns/{campaignId}/sender-routing

Path: campaignId

Body (json): rules array

Replace a campaign's sender routing rules (full replace; [] clears them). Requires Campaigns edit.

PUT /api/v1/campaigns/{campaignId}/sender-routing. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Needs the sender_routing flag.
Each rule: {"provider": "<slug>", "domains": ["<sending domain>"], "inbox_ids": [<id>]}.
provider is an active mailbox provider or security gateway slug (see
analytics_campaign(operation="list-recipient-providers")), one rule per provider. A rule needs a domain
or an inbox; every domain must be the address domain of a workspace inbox and every
inbox a workspace inbox. Prospects on the provider get their first email only from
the rule's inboxes; a rule with no sendable inbox makes them wait. Returns the
routing as segments(operation="get-sender-routing") does.

restore-version

Write. POST https://api.ken.so/v1/segments/{segmentId}/versions/{versionId}/restore

Path: segmentId, versionId

Body (json): confirm boolean, dryRun boolean

Restore a segment to a saved version. dry_run returns the cascade preview and does not write. Each child includes snapshot.

POST /api/v1/segments/{segmentId}/versions/{versionId}/restore. Public. Sends Ken-Version 1.1.
Requires Campaigns edit. Dry-run cascade children include snapshot.
An applying restore that would clear campaign AI output returns 409 conflict with error.impact
until confirm is true. Cascade kind and status are lowercase snake_case.

save-version

Write. POST https://api.ken.so/v1/segments/{segmentId}/versions

Path: segmentId

Body (json): abTestPercentage integer, description string, filterCriteria object, name string, segmentationType string, sortOrder integer, sourceVersionId integer

Save a segment as a new version, applying the given changes. Absent fields keep the live segment's value. Returns segment, version and versionWarning.

POST /api/v1/segments/{segmentId}/versions. Public. Sends Ken-Version 1.1. Requires Campaigns edit.

Applies the fields to the segment and writes one version row. The fields are the
segments(operation="update") fields plus source_version_id. A field you leave out keeps the
live segment's value, or the source_version_id version's value when you give one, so a save
with no fields saves the current state. clear_description and clear_ab_test_percentage send
JSON null, which clears the field; do not send them with a value. segmentation_type is manual,
ai or ab_test; ab_test_percentage is 0 to 100. filter_criteria is the segment filter object
(segments(operation="preview") with no criteria returns the filter catalog), with the camelCase
keys listed on segments(operation="create"), matched case-insensitively (Titles works,
seniority_levels does not); an unknown key is refused before any call, naming it. A
source_version_id of another segment is not_found; another save in progress for the segment
is 409 conflict: retry. When the save lands but version history is not captured, version is
null and versionWarning says so. Replaces the retired segments save_new_version.

set-provider-track

Write. PUT https://api.ken.so/v1/segments/{segmentId}/provider-tracks/{track}

Path: segmentId, track

Body (json): sequence string

Give one provider track its own copy of a segment's sequence, or share the segment's again. Requires Campaigns edit.

PUT /api/v1/segments/{segmentId}/provider-tracks/{track}. Public. Sends Ken-Version 1.1.
client_id is sent as X-Ken-Workspace-Id. Needs the workspace's provider_tracks flag.
Format follows the recipient's mail provider. Inside one campaign, leads split into
provider tracks: Google, Microsoft, Everyone else. A recipient on Google (Google
Workspace or gmail.com) gets plain text: no HTML in the first email, and plain-text
follow-ups until Kenso's HTML follow-up test reads. A recipient on Microsoft
(Microsoft 365 or outlook.com) gets the email as written, HTML included.
track: google, microsoft or other (everyone else).
sequence "own": the track gets a copy of the segment's email sequence. Then read and
replace that copy with the segment-email-sequences operations on the track's
sequenceSegmentId from the response. Editing one track's copy never changes another's.
The segment needs an email sequence of its own first: save the campaign's emails onto
the segment with the segment-email-sequences replace operation, then ask for "own".
sequence "shared": drops the track's copy; its contacts continue on the segment's
sequence at the same step. Both are safe to repeat.
Returns the three tracks as get-provider-tracks does.
Errors (validation_failed detail): feature_disabled, invalid_track, invalid_sequence,
no_sequence, sequence_has_conditions.

update

Write. PATCH https://api.ken.so/v1/segments/{segmentId}

Path: segmentId

Body (json): abTestPercentage integer, description string, filterCriteria object, name string, segmentationType string, sortOrder integer

Update a segment. Absent fields stay unchanged. clear_description and clear_ab_test_percentage send JSON null.

PATCH /api/v1/segments/{segmentId}. Public. Sends Ken-Version 1.1.

Requires Campaigns edit. segmentation_type is manual, ai, or ab_test.
ab_test_percentage is 0 through 100. filter_criteria takes the camelCase keys listed on
segments(operation="create"), matched case-insensitively (Titles works, seniority_levels
does not) and sent camelCased; an unknown key is refused before any call, naming it.
filter_criteria={} clears the segment's filters. Only a manual segment holds filters: the
backend refuses filter_criteria on an ai or ab_test segment (an AI campaign's Default is
ai). Narrow such a campaign with a new manual segment plus process_filters instead.

process_filters

Write.

Assign a Manual segment's contacts from its saved filter criteria (process_filters). Skipping it leaves the segment at zero contacts.

Materialize a Manual segment's membership from its saved filter criteria.

Segments determine how contacts within a campaign are divided for sending.
Each segment is a Kenso campaign grouping. There is no segment export
or refresh step.

Canonical Manual Segmentation Workflow:
---------------------------------------
Manual segments are filter-criteria-driven, not "pick a list of contact IDs".
The full end-to-end workflow is:

1. (optional) segments(operation="preview", campaign_id=...) with no
   criteria - read the filter catalog (valid enum values).
2. (optional) segments(operation="preview", campaign_id=..., criteria={...})
   - sanity-check filter shape and counts. Pass segment_id to include that
   segment's current members in the preview base set, matching
   process_filters.
3. segments(operation="create") with segmentation_type="manual" + filter_criteria -
   persists criteria. Does NOT assign contacts yet.
4. operation="process_filters" - the load-bearing step that materializes contact
   membership from the default segment into the Manual segment. Skipping this
   leaves the segment at zero contacts. Backend requires segmentation_type manual
   or this returns ValidationError.
5. segments(operation="get") - confirm contactCount and readyContactCount.
6. If you need a file, contacts(operation="export_contacts") CSV variants. Campaign
   send/lifecycle is Kenso APIs (the campaign_flow operations). There are no
   segment export or refresh tools.

Updating membership later: segments(operation="update") with new filter_criteria,
then re-run operation="process_filters". segments(operation="activate") /
segments(operation="deactivate") toggle sending only and do not require
re-processing.

Versions: segments(operation="save-version") saves a checkpoint the
dashboard version history lists, segments(operation="restore-version")
restores one (it cascades to the linked sequence and prompt versions), and
segments(operation="list-versions") / segments(operation="get-version")
browse history. Copy another campaign's leads in with
contacts(operation="contact-imports-create").

See docs/manual-segmentation-workflow.md for the full reference, including common
mistakes and verification checklist.

Operations:
-----------
process_filters:
    Requires campaign_id and segment_id (a Manual segment).
    POST /api/v1/campaigns/{campaign_id}/segments/{segment_id}/process-filters.

Filter Criteria Schema (for Manual segmentation):
-------------------------------------------------
Pass as filter_criteria dict. All fields optional, AND-combined between fields,
OR-combined within arrays.

CONTACT FILTERS:
    fullName: {contains?: str, notContains?: str}
        Filter by contact full name substring.
    titles: str[]
        Include contacts whose title contains any of these substrings.
        Example: ["VP", "Director", "Head of"]
    excludeTitles: str[]
        Exclude contacts whose title contains any of these substrings.
    lastJobTitle: {contains?: str, notContains?: str}
        Filter by previous job title (last_job_title column).
    headlines: str[] / excludeHeadlines: str[]
        LinkedIn headline substring match.
    summaryContains: str
        LinkedIn about section keyword search.
    seniorityLevels: str[] / excludeSeniorityLevels: str[]
        Enum values: Training, Entry, Individual, Senior, Manager, Director, VP, CLevel, Owner, Partner
        segments(operation="preview") with no criteria lists them.
    functions: str[] / excludeFunctions: str[]
        Enum values: Engineering, Sales, Marketing, Operations, Finance, etc.
        segments(operation="preview") with no criteria lists them.
    employmentTypes: str[]
        Values: Full-time, Part-time, Contract, Internship, Freelance
    isDecisionMaker: bool
        Filter by decision-maker flag.
    changedJobRecently: bool
        New-hire targeting (high-value signal).
    yearsOfExperience: {min?: float, max?: float}
        Example: {"min": 5, "max": 15}
    yearsInCurrentRole: {min?: float, max?: float}
    yearsInCurrentCompany: {min?: float, max?: float}
    profileCountries: str[] / excludeProfileCountries: str[]
        The stored country text, matched exactly (case too), such as "United States".
    profileState: str / profileCity: str
        Free text contains match.
    skillsContains: str
        Search in skills column (pipe-separated).
    certificationsContains: str
        Search in certifications JSON. Example: "AWS Certified"
    languages: str[]
        Spoken languages. Example: ["English", "Spanish"]
    emailValidity: str[]
        Values: Safe, Invalid, Risky, Unknown, CatchAll, Verified
    emailProviders: str[] / excludeEmailProviders: str[]
        Values: Prospeo, Findymail, LeadMagic, DatabaseLookup, KenFinder (found by Kenso's own finder)
    isPersonalEmail: bool
        Filter personal vs corporate email addresses.
    hasLinkedInUrl: bool
    hasPhone: bool
    hasValidPhone: bool

COMPANY FILTERS:
    companyNames: str[] / excludeCompanyNames: str[]
        Multi-value company name substring match.
    companyDomainContains: str
    companyDescriptionContains: str
    companySpecialitiesContains: str
        Company specialties/focus areas keyword search.
    industries: str[] / excludeIndustries: str[]
        Fixed enum (~150 LinkedIn industries). segments(operation="preview")
        with no criteria lists them.
    companyHeadcount: {min?: int, max?: int}
        Numeric min/max employee count range.
        Example: {"min": 50, "max": 500} for mid-market.
        Example: {"min": 1000} for enterprise only.
    companyFollowers: {min?: int, max?: int}
        LinkedIn follower count (brand-awareness proxy).
    companyFoundedYear: {min?: int, max?: int}
    companyTypes: str[]
        Values: Public Company, Privately Held, Non Profit, Government Agency, etc.
    lastFundingRounds: str[]
        Values: Seed, Series A, Series B, Series C, Series D, Growth, IPO
    totalFunding: {min?: int, max?: int}
        USD amount range.
    technologies: str[] / excludeTechnologies: str[]
        Tech stack filter (e.g. ["Salesforce", "Stripe"]).
        SPARSE FIELD - not all companies have tech data enriched.
        segments(operation="preview") with no criteria lists the enum.
    companyHqCountries: str[] / excludeCompanyHqCountries: str[]
    companyHqState: str / companyHqCity: str

STATUS FILTERS:
    doNotContact: bool
    createdAt: {from?: str, to?: str}
        Date range in ISO format (YYYY-MM-DD).

ACTIVITY FILTERS:
    totalClicks: {min?: int, max?: int}
        Lifetime total email-link clicks summed across ALL of the contact's
        campaigns (contact_email_stats.emails_clicked). Useful in signal-based
        (Trigger) campaigns to segment engaged contacts.
        Example: {"min": 3} for contacts who clicked 3+ times.

AI LEAD SCORE:
    leadQualityScore: {min?: int, max?: int}
        Inclusive bounds on the AI lead score stored in
        lead_quality_scores.score. Integers 1 through 10. 1 is no fit,
        10 is a perfect fit. There is no stored 0. This is not
        contacts.lead_score (the 0-100 rule score).
        A contact with no live score does not match, including a max-only
        bound. Unassigned contacts stay unassigned. Contacts already on
        the default segment stay there. A contact already in this segment
        who no longer matches is moved back to the default the next time
        filters are processed.
        Example: {"min": 8, "max": 10} for the strongest leads.
        Example: {"max": 4} for weak fits that already have a score.
        Non-overlapping ranges can be processed in any order. A shared
        boundary (one segment max 5 and another min 5) overlaps, and the
        first segment processed keeps that score. A contact already
        assigned to another manual segment is not moved.

BEHAVIOR TAGS:
    behaviorTags: list[str]
        Keep contacts whose behavior tags include any of these: what Kenso
        learned from outreach outcomes (for example cold_responder,
        prefers_linkedin, best_window:weekday_morning, replies_in:de).
        Workspace tags always; network tags only with the
        behavior_signals_network feature.
    behaviorTagsExclude: list[str]
        Drop contacts whose behavior tags include any of these (for example
        unsubscribed, hostile, saturated).
        email_confirmed, email_dead_end and left_company cannot be used.
        Example: {"behaviorTags": ["prefers_email"], "behaviorTagsExclude": ["saturated"]}
    Like contact and people filters, these need the behavior_signals
    feature: without it, create and preview refuse them with a
    validation error, and update refuses only a tag the segment does
    not already store (resending the stored tags, removing them or
    renaming the segment works). A segment that already has them is
    skipped by process_filters while the feature is off: its members
    stay where they are and no contact joins it. Until the workspace
    has behavior profiles, behaviorTags
    matches no contact and behaviorTagsExclude drops none. To undo, clear
    both.

AI VARIABLE FILTERS:
    aiVariableFilters: list[{promptId: int, operator: str, value?: str}]
        Per-prompt filter on AI personalization variables. Useful for
        A/B testing campaigns "with vs. without AI" - clone a segment
        and flip operator between Exists and NotExists for the same
        promptId to split contacts into "AI On" / "AI Off" branches.

        operator must be one of these PascalCase names. segments
        reads return the same operator in snake_case ("not_exists"),
        and segments writes take either form:
            "Exists"      - contact has a non-empty response for the prompt
            "NotExists"   - contact has no response (or empty) for the prompt
            "Contains"    - response substring match (value required)
            "NotContains" - response substring NON-match (value required)

        promptId is the backend Prompt PK (ulong on the wire). Discover
        available promptIds via admin_query(operation="fields", campaign_id=...);
        entries are returned in the "AI Variable" group with promptId set.

CUSTOM VARIABLE FILTERS:
    customVariableFilters: list[{variableKey: str, operator: str, value?: str}]
        Per-key filter on the campaign's uploaded custom variables (the
        values stored per contact in contacts.custom_variables_json).
        Only valid on manual segments (segmentation_type="manual"), same as every
        other filter criterion. All entries AND together with each other
        and with every other criterion. Matching is case-insensitive.

        operator must be one of these PascalCase names. segments
        reads return the same operator in snake_case ("is_not_empty"),
        and segments writes take either form:
            "Contains"    - value substring match (value required)
            "NotContains" - value substring NON-match (value required)
            "Equals"      - exact value match (value required)
            "NotEquals"   - exact value NON-match (value required)
            "IsEmpty"     - key absent or value blank (omit value)
            "IsNotEmpty"  - key present with a non-blank value (omit value)

        variableKey is the NORMALIZED catalog key from
        lists(operation="custom-variables-list", campaign_id=...),
        NOT the display name. Always READ the key from that catalog rather
        than deriving it yourself. For reference the normalization is:
        lowercase, collapse each run of non-[a-z0-9] characters to a single
        `_`, then TRIM leading/trailing `_` (e.g. " Renewal Date " ->
        "renewal_date", not "_renewal_date_").

        Absent-key semantics: a contact whose key is missing does NOT match
        Contains/Equals, and DOES match NotContains/NotEquals. IsEmpty
        covers both "key absent" and "value blank". Filters that reference
        a deleted custom variable are kept (not rejected) and simply match
        nothing.

Examples:
    Assign contacts to a Manual segment created with
    segments(operation="create") (the full canonical flow):
    >>> segments(
    ...     operation="process_filters",
    ...     campaign_id=123, segment_id=456
    ... )