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>.

Segments are read-only in the Public API — every endpoint is a GET, with one exception: POST /v1/segments/preview is a non-mutating dry-run that evaluates a candidate predicate without saving anything. Segments are created and maintained from the dashboard or as code in a connected git repository (see Git-backed definitions below).

Lists are different: List definitions are writable through the API with the api.lists.manage scope — create, edit, and delete — while membership stays on the contacts surface (lists on /v1/contacts). See Managing List definitions.

Attributes are also writable. Beyond the read endpoints, you can create, edit, delete, and dry-run-preview attribute definitions with the api.attributes.manage scope — see Managing attribute definitions. Editing the schema can affect the Segments that reference it, so every write reports its mutation class.

How it maps to the dashboard

Scopes

Five 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 and api.lists.manage are write scopes — grant them only to integrations that own your attribute schema or your List definitions respectively, 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.

{
"id": "0192f1a3-...-...",
"name": "Beta cohort",
"key": "beta-cohort",
"description": "Hand-curated early-access users",
"source": "api",
"member_count": 412,
"origin": "managed",
"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. source (api · ui · import · topic_export) records how the List was created — topic_export marks a snapshot List exported from a subscription topic. origin (managed · git) and status (active · archived) follow the same git-backed provenance model as Segments and attributes; a git-backed List also carries source_path.

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. A Segment’s response includes:

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

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, so you can validate before persisting a Segment elsewhere.

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" }
]
}

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:

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
}
}

Git-backed Lists, Segments, and attributes

Lists, Segments, and attribute definitions can all be managed as code in a connected GitHub repository (a List via the manifest’s lists key, a Segment via its own file, an attribute via the attribute schema). When a definition originates from git, its response carries:

Edit git-backed definitions in the repository — SendOps validates and reconciles them on push, and a removed source file moves the definition to archived (a List’s key, a Segment’s or attribute’s source file). These fields are simply absent for dashboard-managed definitions.

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);
}