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

# Audience segments

> Save rule-based groups of your email contacts, count them live, and send posts to them. Growth plan and above.

A **segment** is a saved set of rules over your email contacts — what they
bought, how much they spent, when they last bought, opened or clicked, their
tags, country and how they subscribed. Segments are evaluated **live**: a
count, a member list or a send always uses the rules at that moment, so
"bought in the last 30 days" means the 30 days before the email goes out.

<Note>
  Segments are on the **Growth** plan and above. On other plans every
  segment endpoint answers `403` with `code: FEATURE_LOCKED` and
  `details.requiredPlan: "tier2"` — API keys and MCP included.
</Note>

## Endpoints

| Method | Path | What it does |
| - | - | - |
| `GET` | `/newsletters/segments` | List segments (`page`, `pageSize` up to 100) |
| `POST` | `/newsletters/segments` | Create a segment |
| `POST` | `/newsletters/segments/preview` | Count an unsaved definition (with 5 sample rows) |
| `GET` | `/newsletters/segments/{id}` | Get one segment |
| `POST` | `/newsletters/segments/{id}` | Update name, description, rules or smart tag |
| `DELETE` | `/newsletters/segments/{id}` | Delete it (its smart tag is taken back) |
| `GET` | `/newsletters/segments/{id}/count` | Live count of active contacts |
| `GET` | `/newsletters/segments/{id}/subscribers` | Members, cursor-paginated (`limit`, `after`) |

## Definition

Rules sit in **groups**. Rules inside a group combine with the group's
`match`; groups combine with the top-level `match` — `all` is AND, `any` is
OR. Up to 10 groups of 20 rules.

```json theme={"system"}
{
  "match": "any",
  "groups": [
    {
      "match": "all",
      "rules": [
        { "type": "bought", "productId": "665f1c2a9b3e4a0012ab34cd" },
        { "type": "spent", "op": "gt", "amountCents": 5000 }
      ]
    },
    { "rules": [{ "type": "tag", "tag": "vip" }] }
  ]
}
```

This is "(bought the course **and** spent more than \$50) **or** tagged vip".

| `type` | Fields | Matches |
| - | - | - |
| `bought` | `productId` | Bought this product or subscription |
| `notBought` | `productId` | Never bought it (includes people who never bought) |
| `spent` | `op` (`gt` / `lt`), `amountCents` | Total spent in your live store, in your account currency |
| `boughtWithin` | `days` | Last purchase within the last N days |
| `notBoughtWithin` | `days` | Past buyers whose last purchase is older than N days |
| `engagedWithin` | `days`, `event` (`opened`/`clicked`/`any`) | Opened or clicked one of your emails in the last N days |
| `tag` / `notTag` | `tag` | Carries (or not) this tag, exact match (tags you add on a customer's CRM page are contact tags too) |
| `country` | `countries` (ISO codes) | Billing country of their latest purchase |
| `source` | `form`, `checkout`, `import`, `dashboard`, `api`, `recommendation` | How they joined your list (`recommendation`: another creator's newsletter recommendation) |

Purchase totals are rebuilt from your sales every night (and a new purchase
moves "last purchase" right away). Contacts added before segments shipped
have no `source`.

## Count a segment before saving it

```bash theme={"system"}
curl -X POST https://api.pocketsflow.com/newsletters/segments/preview \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "definition": { "groups": [{ "rules": [{ "type": "notBoughtWithin", "days": 90 }] }] } }'
```

```json theme={"system"}
{ "count": 214, "sample": [{ "_id": "…", "email": "ann@example.com", "name": "Ann" }], "computedAt": "2026-10-16T12:00:00.000Z" }
```

## Smart tags

Give a segment a `smartTag` and every member carries that tag. It is
refreshed every night: new members get it, people who left the segment lose
it — only where the segment added it, so a tag you typed by hand is never
removed. One smart tag per segment, each tag used by one segment (`409`
otherwise). The dashboard offers three to start: `customer`, `vip` (spent
over \$200) and `lapsed` (no purchase in 90 days).

## Send a post to a segment

Set `segmentId` on `POST /newsletters/posts` (or update a post with it), then
send or schedule it as usual. The segment's rules are evaluated when the post
goes out. A deleted segment, or a plan that no longer includes segments,
leaves the post with no audience: it fails instead of sending to someone else.

Automations can use segments too: limit a trigger to a segment, or branch on
**Is in segment** in a condition.

## MCP

AI agents get `list_segments`, `create_segment`, `get_segment`,
`get_segment_count` and `preview_segment`. See [MCP server](/api-reference/mcp-server).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.