Pause or resume a Segment
Pauses (paused) or resumes (active) membership evaluation. On
writes, {id} resolves as a UUID or, failing that, as the Segment's
org-unique key.
A paused Segment is not reconciled, so its stored count is a snapshot
from whenever it was paused. Resuming therefore evaluates inline and the
response carries the fresh count with evaluation: "complete" (or a
null count with evaluation: "queued"). Pausing needs no evaluation —
the stored count is the last real one — and returns no evaluation.
A Segment whose predicate is invalid cannot be activated; fix the
predicate with PUT /v1/segments/{id} first (422).
Path parameters
id string required The Segment's UUID or, when the value does not parse as a UUID, its org-unique key. Unknown handles read as 404 not_found. Accepted on every Segment route, read and write alike.
Request body
Content type: application/json
status string enum required paused stops membership evaluation; active resumes it and re-evaluates inline.
One of: active, paused
Responses
Errors follow the RFC 7807 problem format — see the error reference.
id string<uuid> required name string required key string required Org-unique slug, stable across renames.
description string required source string required The SendQL predicate that defines membership.
profile_version integer required SendQL profile version the source was compiled under.
eval_class string enum required How membership is reconciled: incremental (re-evaluated on an
attribute change), sweep (periodic full re-evaluation, for
time-relative or event predicates), or both.
One of: incremental, sweep, both
status string enum required invalid means the predicate no longer compiles (e.g. a referenced
attribute was deleted); fix the predicate with PUT /v1/segments/{id}
to re-activate.
archived is a retired segment — deactivated but preserved.
One of: active, paused, invalid, archived
member_count integer<int64> | null required Cached count of current members from the last reconcile, and null
when the segment has never been evaluated. Null is not zero: zero
means the predicate matched nobody, null means nothing has asked yet.
A newly created segment is null only until its first evaluation
completes — see evaluation.
evaluation string enum optional Present only on a write response. complete means the save evaluated
the membership before returning and member_count is that answer;
queued means the evaluation exceeded its budget or failed, a
background reconcile was enqueued, and member_count is null until it
finishes. Absent on reads.
One of: complete, queued
eval_warning string optional A standing "evaluation disrupted" warning, present when an attribute the predicate references was mutated disruptively (renamed or retyped via the management API). The segment keeps evaluating best-effort; the warning clears when the predicate is re-saved. Absent when the segment is healthy.
eval_warning_at string<date-time> optional Time the standing eval_warning was raised; absent when none.
last_evaluated_at string<date-time> optional Time of the last reconcile; absent until the first evaluation.
content_hash string optional The optimistic-concurrency token over the segment's author-editable
definition. Send it back as expected_content_hash on
PUT /v1/segments/{id} and the edit is refused (409) rather than
clobbering a concurrent one. Absent on a row that predates the
column, until its next managed write recomputes it.
warnings array<string> optional Non-blocking findings from the SendQL analyzer for the definition just saved — present only on a write response. A segment with warnings is saved, not rejected.
requires array<object> optional Everything this definition still depends on, with each dependency's state. Present on the write responses and on the detail read (the polling surface); absent on the collection read. An empty array means nothing is outstanding — see V1Requirement.
Each entry in requires:
kind string enum required The namespace key is looked up in. Branch on this; never parse detail.
One of: template, segment, list, topic, identity, channel, attribute, activity_property, asset
key string required The identifier as the definition names it — a template name, a segment id or key, a from-address. Empty for a requirement about the ABSENCE of a reference: a send with no topic at all names no topic.
status string enum required ok — resolves and is usable now.
missing — nothing in this organization answers to that key. Correct
the reference, or create the thing.
not_ready — it exists, in a state that cannot be used yet. Usually
a wait, and retrying the identical request is the move. Treating this
as missing sends you hunting for a typo that is not there.
One of: ok, missing, not_ready
detail string required The state, in the words that say which state — deploy_state=pending, member_count=null (evaluation queued). For display and logs; do not parse it.
fix string required The call that clears this requirement, as an HTTP route where there is one and as a plain instruction where there is not (a template deploy is waited for, not called). Empty on an ok entry.
created_at string<date-time> required updated_at string<date-time> required code is conflict.
application/problem+json validation_failed Problem. When the refusal is about a
reference — a segment key, template slug, topic or attribute name the
organization does not have — it additionally carries validation_code,
field, line/column, missing, candidates and next_step, so a
client can correct the call without a second round of guessing. See
ValidationProblem.
application/problem+json code is internal_error. The
request_id field can be quoted to SendOps support to investigate.
application/problem+json