---
title: "Segments"
description: "Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of."
url: https://www.unitpost.com/docs/api/segments
section: API reference
updated: 2026-07-31
---
# Segments

## Segments

> Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of.

Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/api/segments.

## Operations

### `GET /api/v1/segments`

List segments

Retrieve a list of the segments in your workspace, cursor-paginated. A segment is a saved group of contacts you can target when sending a campaign. Create one with [Create a segment](#post-segments), or list a segment's members with [List segment members](#get-segments-id-contacts). Requires the `segments:read` capability.

### `POST /api/v1/segments`

Create a segment

Create a segment — a named group of contacts you can target when sending a campaign. Once created, add contacts with [Add a member](#post-segments-id-contacts) and target it from [Create a campaign](#post-email-campaigns). To let recipients opt out of a category of mail instead, see [Create a topic](#post-email-topics). Requires the `segments:write` capability.

### `GET /api/v1/segments/{id}`

Retrieve a segment

Retrieve a single segment by `id`, including its name and member count. To page through the contacts inside it, use [List segment members](#get-segments-id-contacts). Requires the `segments:read` capability.

### `PATCH /api/v1/segments/{id}`

Update a segment

Update a segment's editable metadata, such as its name. To change who's in the segment, add or remove members with [Add a member](#post-segments-id-contacts) and [Remove a member](#delete-segments-id-contacts-contact). Requires the `segments:write` capability.

### `DELETE /api/v1/segments/{id}`

Delete a segment

Delete a segment. The contacts themselves are untouched — only the grouping is removed. This is blocked with `409` while an active campaign still targets the segment; cancel or finish that campaign first (see [List campaigns](#get-email-campaigns)). Requires the `segments:write` capability.

### `GET /api/v1/segments/{id}/contacts`

List segment members

Retrieve the contacts in a segment, cursor-paginated. Add a contact with [Add a member](#post-segments-id-contacts) or take one out with [Remove a member](#delete-segments-id-contacts-contact). Requires the `segments:read` capability.

### `POST /api/v1/segments/{id}/contacts`

Add a member

Add a contact to a segment, referenced by contact id or email. The operation is idempotent — adding a contact that's already a member is a no-op and still succeeds. See the current members with [List segment members](#get-segments-id-contacts). Requires the `segments:write` capability.

### `DELETE /api/v1/segments/{id}/contacts/{contact}`

Remove a member

Remove a contact from a segment, referenced by contact id or email. The contact itself is not deleted — only its membership. Add it back any time with [Add a member](#post-segments-id-contacts). Requires the `segments:write` capability.

## Related

- [Topics](https://www.unitpost.com/docs/api/topics): Subscription categories (e.g. Promotions) recipients can opt out of without leaving your list, independent of segment membership. Scope a campaign to a topic and opted-out contacts are skipped automatically.
- [Campaigns](https://www.unitpost.com/docs/api/campaigns): One-to-many sends to a segment or an inline recipient list. Draft, validate, schedule, send, pause, resume, and cancel — with a pre-send report that catches problems before anything goes out.
- [Templates](https://www.unitpost.com/docs/api/templates): Reusable email designs in the canonical block-based JSON format the dashboard editor produces, with per-recipient `{{variables}}` filled at send time.