Preview an attribute edit's impact
Dry-runs a proposed edit and returns its mutation_class and projected
impact — the segments that reference the attribute and, for a disruptive
edit, each one's typecheck outcome plus the org-wide drop-out projection —
without writing anything. The body is the proposed definition (same shape
as the PUT edit body). Use it before committing a disruptive change.
Path parameters
id string required The attribute's UUID or, when the value does not parse as a UUID, its org-unique name — the same name PUT /v1/attributes/by-name/{name} is keyed on and a Segment predicate compiles against. Unknown handles read as 404 not_found.
Request body
Content type: application/json
name string required Lowercase identifier (letters, digits, underscore), referenced in SendQL as attr.<name>.
type string enum optional Required for an ordinary attribute; ignored when formula is set (the derived type is inferred).
One of: string, number, bool, datetime, enum
enum_values array<string> optional Required when type is enum; must be empty/omitted otherwise.
description string optional formula string optional Creates a derived attribute (SND-1067) whose value SendOps computes and
maintains from the contact's event/activity stream. One aggregate over one
source: exists, count, first, or last of a SES event name (send,
open, click, …) or activity.<name> — e.g. exists(send),
count(activity.order). The value type is inferred; type/enum_values
are ignored. Derived attributes are managed-only (not promotable) and their
formula is immutable (change = delete + recreate). Create-only.
Responses
Errors follow the RFC 7807 problem format — see the error reference.
mutation_class string enum required How an edit affects dependent Segment predicates: free (no effect),
safe_but_stale (an enum value was removed; predicates stay valid), or
disruptive (a rename or cast-class change that raises a standing per-segment
warning).
One of: free, safe_but_stale, disruptive
impact object required The projected (preview) or committed (apply) impact of a mutation on dependent Segments and Workflows.
Fields of impact:
affected_segments array<object> required Each entry in affected_segments:
id string<uuid> required name string required typecheck_ok boolean required Whether the segment's predicate still type-checks under the change. Always true for a free / safe-but-stale edit; may be false for a disruptive one.
warning string optional The standing "evaluation disrupted" warning the edit would raise (or did); absent when none.
affected_workflows array<object> required Each entry in affected_workflows:
id string<uuid> required name string required key string required status string required The workflow's lifecycle status (draft, active, paused, archived, invalid).
projected_dropout integer<int64> required Org-wide count of contacts that drop out of the affected segments under the change (values that no longer cast, or carriers of a renamed/deleted attribute). 0 unless the change is disruptive.
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