Lists & Segments

The audience API exposes the same Lists, Segments, and custom attributes your dashboard shows. There are three resources:

• Lists — static audiences with explicit membership. A contact is in a List because it was added, and stays until it’s removed.
• Segments — dynamic audiences defined by a SendQL predicate. Membership is computed from each contact’s attributes and engagement, and is re-evaluated continuously — you never add members by hand.
• Attributes — the registry of custom attribute definitions (name, type, optional enum values). This is the schema that Segment predicates reference as attr.<name>.

All three are writable, each behind its own .manage scope. Nothing on this surface is read-only because it came from somewhere else: a definition belongs to your organization and any caller holding the scope can author it.

• Segments — create, edit, delete, pause/resume and force-evaluate with api.segments.manage; lint and size a candidate predicate first with the two non-mutating POSTs under api.segments.view. See Managing Segment definitions.
• Lists — create, edit and delete List definitions with api.lists.manage, while membership stays on the contacts surface (lists on /v1/contacts). See Managing List definitions.
• Attributes — create, edit, delete and dry-run-preview definitions with api.attributes.manage. Editing the schema can affect the Segments that reference it, so every write reports its mutation class.

What a Segment’s members are is the one thing you cannot write: membership is the live truth value of the predicate, recomputed, never assigned.

How it maps to the dashboard

Scopes

Six scopes gate this surface, each granted by the matching dashboard permission:

api.attributes.view is the safe one to hand to an integration that only needs to know what fields exist (for example, to render a Segment-builder UI) without being able to read any recipient. api.attributes.manage, api.lists.manage and api.segments.manage are write scopes — grant them only to integrations that own the corresponding definitions, since a disruptive attribute edit can flip dependent Segments into a warning state, and a List delete leaves its membership log orphaned (see below).

Pagination

List and Segment collections (/v1/lists, /v1/segments, /v1/attributes) are bounded per org and returned newest-first. Member collections (/v1/lists/{id}/members, /v1/segments/{id}/members) can be large and are cursor-paginated — follow pagination.next_cursor until it’s null. Every collection response carries data plus a pagination object.

Lists

A List is a static membership set. Each member carries an added_at timestamp — when the contact was put on the List — its email, which is the contact’s current address (not the one it was added under), and its external_id, your own identifier for the contact (null when it has none).

{
"contact_id": "0192f1b7-...-...",
"email": "jane@example.com",
"external_id": "user_8812",
"added_at": "2026-06-10T14:22:00Z"
}

If you keep a List in step with your own user table — adding users with PUT /v1/contacts/by-external-id/{external_id} and lists — find the members who are no longer users by comparing each member’s external_id with your user ids, not by email. A user who changed their address keeps their external_id, so an email diff would wrongly read them as a leaver plus a new user. A member whose external_id is null was added some other way; decide separately whether your sync owns it.

A List definition looks like this:

{
"id": "0192f1a3-...-...",
"name": "Beta cohort",
"key": "beta-cohort",
"description": "Hand-curated early-access users",
"source": "api",
"member_count": 412,
"status": "active",
"created_at": "2026-05-01T09:00:00Z",
"updated_at": "2026-06-10T14:22:00Z"
}

key is an org-unique slug that stays stable across renames — prefer it over name when you reference a List from your own systems, and it is what {id} falls back to on a write when the value is not a UUID. source (api · ui · import · topic_export) records how the List was created — topic_export marks a snapshot List exported from a subscription topic, and import one applied from a bundle. status is active or archived; archiving never blocks membership or mailability.

Managing List definitions

With the api.lists.manage scope you can author static-List definitions over the API — membership itself is managed separately, via lists on the contacts surface:

Segments

A Segment is defined by a SendQL predicate that resolves to a boolean per contact. The predicate references custom attributes as attr.<name> (the names come from /v1/attributes) plus engagement events and subscription state.

attr.plan = "pro" and attr.region = "eu"

Over the API that predicate travels as a JSON string — the source field of a Segment, and the body of a preview.

A Segment’s response includes:

Segment members carry entered_at — when the contact most recently entered the Segment (membership can churn as attributes change).

Linting a predicate

POST /v1/segments/validate parses and analyses a candidate SendQL predicate against your attribute registry and returns positioned diagnostics plus the attributes the predicate reads. Nothing is persisted, no contacts are read, and no sample is returned — this is the cheap loop to run while you are still typing.

It always answers 200, including for a predicate that does not compile: valid is the answer and the diagnostics say where and why. The one 422 is a body with no source at all.

Previewing a predicate

POST /v1/segments/preview evaluates a candidate predicate against your current contacts without saving anything — the same call the dashboard’s predicate editor makes. It returns the match count, the inferred eval_class, and a small sample of matching contacts. An invalid predicate returns 422 validation_failed with the compile error. Run validate first for the diagnostics, preview next for the size, then commit with POST /v1/segments.

curl -s -X POST 'https://api.sendops.dev/v1/segments/preview' \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"source": "attr.plan = \"pro\" and attr.region = \"eu\""}'

{
"count": 128,
"eval_class": "incremental",
"sample": [
  { "contact_id": "0192f1a3-...", "email": "jane@example.com" }
]
}

Managing Segment definitions

With the api.segments.manage scope you can author Segments over the API.

Concurrency. Send expected_content_hash (the content_hash from a previous read) on an edit and it becomes conditional: if the stored hash has moved on the edit is refused with 409 conflict and the response carries the current hash, so a retry is one re-read away. Omit it and there is no check.

Deleting is refused while something depends on it. A 409 names the dependents in referenced_by as {kind, key, name} — an active workflow whose trigger enrolls on this Segment, or a draft/scheduled broadcast that has it as an audience. Both would otherwise fail quietly and later. Repoint or remove the dependent, then retry.

Saving a Segment mails nobody: a broadcast or a workflow is what sends.

Attributes

The attribute registry is the schema Segment predicates compile against. Each definition has a lowercase name (referenced in SendQL as attr.<name>), a type (string · number · bool · datetime · enum), and, for enum, the allowed enum_values.

{
"id": "0192f1a3-...",
"name": "plan",
"type": "enum",
"enum_values": ["free", "pro", "enterprise"],
"description": "Billing plan",
"created_at": "2026-04-12T10:00:00Z",
"updated_at": "2026-04-12T10:00:00Z"
}

Managing attribute definitions

With the api.attributes.manage scope you can author the attribute registry over the API — the same schema your Segments compile against:

{id} on every attribute route takes the attribute’s name as readily as its UUID — the same name PUT /v1/attributes/by-name/{name} is keyed on and a predicate compiles against, so GET /v1/attributes/plan works. Activity properties follow the same rule with their dotted handle: GET /v1/activity-properties/order.total, split on the last dot, since an activity name may contain one and a property name may not.

The request body for create, edit, and preview is the same shape: name (lowercase identifier referenced as attr.<name>), type (string · number · bool · datetime · enum), enum_values (required when type is enum, rejected otherwise), and an optional description.

Mutation classes and impact

Every edit, delete, and preview is classified by how it affects dependent Segment predicates:

A disruptive edit (and every delete) returns an impact block:

# Dry-run a type change before committing it (api.attributes.manage)
curl -s -X POST 'https://api.sendops.dev/v1/attributes/0192f1a3-.../preview' \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"name": "plan", "type": "number"}'

{
"mutation_class": "disruptive",
"impact": {
  "affected_segments": [
    { "id": "0192f1a3-...", "name": "EU pro users", "typecheck_ok": false, "warning": "attribute \"plan\" changed type; predicate no longer type-checks" }
  ],
  "projected_dropout": 128
}
}

Version history

Every List, Segment and attribute keeps a version history, and every write snapshots the previous definition before it applies — so a bad edit is one call from being undone, and the snapshot records who made the change.

The reads sit on the resource’s .view scope; the restore needs .manage. A restore is an ordinary write — it snapshots the state it replaces, so restoring twice leaves two rows in the history and the definition where you asked for it.

Keeping definitions in your own repository

Nothing here is owned by a repository, but plenty of teams want these definitions reviewed in one. That is what POST /v1/import is for: keep sendops.json and its files in your repo, and have CI push the bundle. GET /v1/export produces the same shape deterministically, so committing an export on a schedule does not generate a diff every night. Imports go through the same authoring services as the calls above — same validation, same version snapshots, same concurrency — and dry_run defaults to true, so a pull-request job plans without writing. See Push from CI.

Worked example: export a Segment’s members

Resolve the Segment by its stable key, then page its members to the end.

async function* segmentMembers(segmentId) {
let url = new URL(
  `/v1/segments/${segmentId}/members?limit=200`,
  "https://api.sendops.dev",
).toString();
while (url) {
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.SENDOPS_API_KEY}` },
  });
  if (!res.ok) throw new Error(`status ${res.status}`);
  const body = await res.json();
  for (const m of body.data) yield m;
  url = body.pagination.next_cursor
    ? new URL(
        `/v1/segments/${segmentId}/members?limit=200&cursor=${body.pagination.next_cursor}`,
        "https://api.sendops.dev",
      ).toString()
    : null;
}
}

for await (const m of segmentMembers("0192f1a3-...")) {
console.log(m.email, m.entered_at);
}