---
title: Segments
description: Saved filters over your contacts, used as broadcast audiences.
---

A segment is a saved group of contacts you can send a [broadcast](/docs/concepts/broadcasts) to. Create segments in the dashboard under **Audience → Segments**, or through the API.

There are two kinds:

- **Filter segment.** It stores a filter, not a list of people. A contact who starts matching the filter is in the segment at once, and the contact count is worked out when you read it.
- **Manual segment.** Created without a filter. You add and remove contacts yourself, in the dashboard or with `POST /contacts/{id}/segments/{segmentId}` and `DELETE /contacts/{id}/segments/{segmentId}`.

A filter can test a contact's email, name, subscribe state and creation date, and any [custom property](/docs/concepts/contacts). Operators include equals, contains, is set, is not set and date comparisons, and conditions combine with and/or.

## Using a segment

- **Broadcasts.** Choose a segment as the audience. The people who get the email are worked out when it sends, with the same filter as the count you saw before. Contacts who are unsubscribed team-wide, or who left the broadcast's sending domain, are always left out.
- **Contacts view.** Filter the list by segment. The CSV export follows the same filter.

```sh
curl -X POST "https://api.billionsend.com/segments" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trial users",
    "filter": { "match": "all", "conditions": [{ "field": "property:plan", "op": "equals", "value": "trial" }] }
  }'
```

`GET /segments/{id}` includes the live `contact_count`, and `GET /segments/{id}/contacts` lists the members. An invalid filter returns `422` and is never stored.

## One segment per brand

If each of your domains is its own brand, bind a segment to the domain it belongs to by setting `domain_id`, when you create it or later with `PATCH /segments/{id}`, or by picking the domain in the dashboard.

- A broadcast to a bound segment must be sent from that domain. From any other domain the broadcast calls return `422`.
- A segment with no domain works with every domain. `"domain_id": null` makes a bound segment team-wide again.
- A domain cannot be deleted while segments are bound to it (`409`).

[Topics](/docs/concepts/topics) can be bound the same way. Together they keep each brand's audience, topics and opt-outs apart; see [Unsubscribes](/docs/concepts/unsubscribes).

## API keys limited to a domain

An API key limited to one domain can only create segments bound to that domain, and cannot make one team-wide.
