Segments

Segments group contacts based on shared attributes or behaviors. There are two types:

Dynamic — membership is evaluated on-the-fly using filter conditions against contact data and event history.
Static — membership is managed manually by adding or removing specific email addresses.

All segment endpoints require a secret key (sk_*).

Filter condition schema

Dynamic segments use a nested FilterCondition object to define who belongs to the segment.

{
  "logic": "AND",
  "groups": [
    {
      "filters": [
        {
          "field": "data.plan",
          "operator": "equals",
          "value": "premium"
        },
        {
          "field": "subscribed",
          "operator": "equals",
          "value": true
        }
      ]
    }
  ]
}

Available operators

Operator	Description
`equals`	Exact match
`notEquals`	Does not match
`contains`	String contains value
`notContains`	String does not contain value
`greaterThan`	Numeric greater than
`lessThan`	Numeric less than
`greaterThanOrEqual`	Numeric greater than or equal
`lessThanOrEqual`	Numeric less than or equal
`exists`	Field is present and non-null
`notExists`	Field is absent or null
`within`	Date is within the last N `unit` (days/hours/minutes)
`olderThan`	Date is older than N `unit`
`triggered`	Event was tracked at least once
`triggeredWithin`	Event was tracked within the last N `unit`
`triggeredOlderThan`	Event was last tracked more than N `unit` ago
`notTriggered`	Event has never been tracked

For time-based operators (within, olderThan, triggeredWithin, triggeredOlderThan) also provide:

value — the numeric amount
unit — one of days, hours, or minutes

List segments

GET /segments Returns all segments for the authenticated project.

Example

curl --request GET \
  --url https://next-api.useplunk.com/segments \
  --header 'Authorization: Bearer sk_live_yourkey'

200

[
  {
    "id": "clx_seg_abc123",
    "name": "Premium Users",
    "type": "DYNAMIC",
    "memberCount": 843,
    "trackMembership": true,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Create segment

POST /segments Creates a new segment.

Body parameters

name

string

required

Segment name.

type

string

default:"DYNAMIC"

Segment type: DYNAMIC or STATIC.

condition

object

Filter condition defining dynamic membership. Required when type is DYNAMIC.

Show FilterCondition properties

condition.logic

string

required

How to combine groups: AND or OR.

condition.groups

array

required

Array of filter groups. Each group contains an array of filters.

Show FilterGroup properties

condition.groups[].filters

array

required

Array of filter conditions.

Show SegmentFilter properties

field

string

required

Contact field to test, e.g. data.plan, subscribed, or an event name for event-based operators.

operator

string

required

Comparison operator (see table above).

value

any

Value to compare against. Not required for existence or event-presence operators.

unit

string

Time unit for date/event operators: days, hours, or minutes.

description

string

Optional description.

trackMembership

boolean

default:"false"

When true, Plunk tracks when contacts enter and exit this segment and fires segment.<slug>.entry / segment.<slug>.exit system events that can trigger workflows.

curl --request POST \
  --url https://next-api.useplunk.com/segments \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Active Premium Users",
    "type": "DYNAMIC",
    "condition": {
      "logic": "AND",
      "groups": [
        {
          "filters": [
            { "field": "data.plan", "operator": "equals", "value": "premium" },
            { "field": "subscribed", "operator": "equals", "value": true }
          ]
        }
      ]
    },
    "trackMembership": true
  }'

Get segment

GET /segments/:id Retrieves a single segment by ID, including its current member count.

Path parameters

string

required

The segment ID.

Example

curl --request GET \
  --url https://next-api.useplunk.com/segments/clx_seg_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

Update segment

PATCH /segments/:id Updates a segment’s name, description, filter condition, or membership tracking setting.

Path parameters

string

required

The segment ID.

Body parameters

name

string

Segment name.

description

string

Segment description.

condition

object

Updated filter condition object.

trackMembership

boolean

Enable or disable membership tracking.

Example

curl --request PATCH \
  --url https://next-api.useplunk.com/segments/clx_seg_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Active Premium Users (Updated)",
    "trackMembership": false
  }'

Delete segment

DELETE /segments/:id Permanently deletes a segment.

Deleting a segment that is used by a campaign or workflow will break those references.

Path parameters

string

required

The segment ID.

Returns 204 No Content on success.

Example

curl --request DELETE \
  --url https://next-api.useplunk.com/segments/clx_seg_abc123 \
  --header 'Authorization: Bearer sk_live_yourkey'

List contacts in segment

GET /segments/:id/contacts Returns a paginated list of contacts that currently belong to the segment.

Path parameters

string

required

The segment ID.

Query parameters

page

number

default:"1"

Page number (1-indexed).

pageSize

number

default:"20"

Contacts per page. Maximum 100.

Example

curl --request GET \
  --url 'https://next-api.useplunk.com/segments/clx_seg_abc123/contacts?page=1&pageSize=50' \
  --header 'Authorization: Bearer sk_live_yourkey'

Add contacts to static segment

POST /segments/:id/members Adds contacts to a static segment by email address. Creates any contacts that do not yet exist.

Path parameters

string

required

The segment ID. The segment must be of type STATIC.

Body parameters

emails

string[]

required

Array of email addresses to add to the segment.

Example

curl --request POST \
  --url https://next-api.useplunk.com/segments/clx_seg_abc123/members \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "emails": ["[email protected]", "[email protected]"]
  }'

Remove contacts from static segment

DELETE /segments/:id/members Removes contacts from a static segment by email address.

Path parameters

string

required

The segment ID. The segment must be of type STATIC.

Body parameters

emails

string[]

required

Array of email addresses to remove from the segment.

Example

curl --request DELETE \
  --url https://next-api.useplunk.com/segments/clx_seg_abc123/members \
  --header 'Authorization: Bearer sk_live_yourkey' \
  --header 'Content-Type: application/json' \
  --data '{
    "emails": ["[email protected]"]
  }'

Overview

Endpoints

Filter condition schema

Available operators

List segments

Create segment

Body parameters

Get segment

Path parameters

Update segment

Path parameters

Body parameters

Delete segment

Path parameters

List contacts in segment

Path parameters

Query parameters

Add contacts to static segment

Path parameters

Body parameters

Remove contacts from static segment

Path parameters

Body parameters

Build docs developers (and LLMs) love

Overview

Endpoints

​Filter condition schema

​Available operators

​List segments

​Create segment

​Body parameters

​Get segment

​Path parameters

​Update segment

​Path parameters

​Body parameters

​Delete segment

​Path parameters

​List contacts in segment

​Path parameters

​Query parameters

​Add contacts to static segment

​Path parameters

​Body parameters

​Remove contacts from static segment

​Path parameters

​Body parameters

Build docs developers (and LLMs) love

Filter condition schema

Available operators

List segments

Create segment

Body parameters

Get segment

Path parameters

Update segment

Path parameters

Body parameters

Delete segment

Path parameters

List contacts in segment

Path parameters

Query parameters

Add contacts to static segment

Path parameters

Body parameters

Remove contacts from static segment

Path parameters

Body parameters