Audience segments

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.

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.

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.

{
  "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

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

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

Overview

API reference

Node.js SDK

Webhooks

Endpoints

Definition

Count a segment before saving it

Smart tags

Send a post to a segment

MCP

​Endpoints

​Definition

​Count a segment before saving it

​Smart tags

​Send a post to a segment

​MCP

Endpoints

Definition

Count a segment before saving it

Smart tags

Send a post to a segment

MCP