> ## Documentation Index
> Fetch the complete documentation index at: https://dugble.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Segments

> Group contacts into explicit audiences for targeting.

Segments are explicit groups of contacts that you can use when targeting bulk messaging.

They are intentionally simple: a contact either belongs to a segment or it does not.

## When to use segments

Use segments for audience selection such as:

* customers on a specific plan,
* users in a lifecycle stage,
* attendees for an event,
* recipients selected by an internal workflow.

Segments describe **who you want to target**. They do not describe whether the contact is allowed or willing to receive a particular category of message.

## Membership and preferences are separate

A contact can belong to a segment while being opted out of a topic, globally unsubscribed from email, or suppressed.

That separation lets your application keep business targeting independent from messaging eligibility.

## Segment membership

Contacts can belong to multiple segments at the same time. Membership is explicit and can be added or removed without changing the contact profile itself.

For endpoint details for creating segments or managing contact membership, see the Segments and Contacts sections in the API Reference.

## Audience size

Use the dedicated audience-size endpoint when you only need the current number of contacts assigned to a segment:

```http theme={null}
GET /segments/{segment_id}/audience-size
```

```bash theme={null}
curl --request GET \
  --url https://api.dugble.com/segments/$SEGMENT_ID/audience-size \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Accept: application/json"
```

A successful response returns the segment ID and membership count:

```json theme={null}
{
  "success": true,
  "data": {
    "segment_id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794",
    "count": 1250
  }
}
```

The count represents **segment membership**, not final delivery eligibility. A member may still be globally unsubscribed, opted out of a topic, or suppressed when a broadcast is prepared.

<Note>
  Use `GET /segments/{segment_id}/audience-size` when you only need the size. You do not need to page through the segment's contacts and count them yourself.
</Note>

## List segments with limit and offset

`GET /segments` uses `limit` and `offset` pagination:

```http theme={null}
GET /segments?limit=50&offset=0
```

The pagination rules are:

* omitted or non-positive `limit` uses `50`,
* `limit` values above `100` are capped at `100`,
* omitted or negative `offset` uses `0`,
* malformed numeric values such as `limit=abc` return a bad-request error.

The response `data` is an array of segments. There is no cursor or `has_more` field for this endpoint.

## List contacts in a segment

`GET /segments/{segment_id}/contacts` uses the same `limit` and `offset` rules:

```bash theme={null}
curl --request GET \
  --url "https://api.dugble.com/segments/$SEGMENT_ID/contacts?limit=100&offset=0" \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Accept: application/json"
```

Each returned contact includes its contact ID, team ID, email, optional first and last name, global email unsubscribe state, and timestamps.

To read the full membership set, continue increasing `offset` by the number of contacts returned until a page contains fewer contacts than the effective limit.