Segments

List segments

GET/api/v1/segments

GET /segments
curl -X GET 'https://www.unitpost.com/api/v1/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment",
      "id": "id_123",
      "name": "Example",
      "description": "string",
      "type": "static",
      "filter": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

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, or list a segment's members with List segment members. Deleted (archived) segments are hidden; pass ?archived=true to list only archived ones, which can be restored for 30 days. Requires the segments:read capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedboolean · queryWhen true, list only archived segments instead of active ones.
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200401422

Create a segment

POST/api/v1/segments

POST /segments
curl -X POST 'https://www.unitpost.com/api/v1/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Active customers"
  }'
Response · 201
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a segment — a named group of contacts you can target when sending a campaign. Once created, add contacts with Add a member and target it from Create a campaign. A dynamic segment's filter is evaluated live: a condition on a custom field uses the field's default_value for any contact that has no value, and is_set / is_not_set check whether the contact itself has a value. To let recipients opt out of a category of mail instead, see Create a topic. Requires the segments:write capability.

Request body4 fields
FieldTypeDescription
namerequiredstring—
descriptionstring—
typeenumstatic | dynamic—
filterobjectDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
Response · 201 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
201401422

Retrieve a segment

GET/api/v1/segments/{id}

GET /segments/{id}
curl -X GET 'https://www.unitpost.com/api/v1/segments/seg_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single segment by id, including its name and member count. To page through the contacts inside it, use List segment members. Requires the segments:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a segment

PATCH/api/v1/segments/{id}

PATCH /segments/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/segments/seg_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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 and Remove a member. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
namestring—
descriptionstring | null—
filterobjectDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200401404422

Delete a segment

DELETE/api/v1/segments/{id}

DELETE /segments/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/segments/seg_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

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). Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

List segment members

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

GET /segments/{id}/contacts
curl -X GET 'https://www.unitpost.com/api/v1/segments/seg_123/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment_member",
      "contact_id": "contact_123",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve the contacts in a segment, cursor-paginated. Add a contact with Add a member or take one out with Remove a member. Requires the segments:read capability.

Parameters4 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200401404422

Add a member

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

POST /segments/{id}/contacts
curl -X POST 'https://www.unitpost.com/api/v1/segments/seg_123/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": "customer@example.com"
  }'
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "segment_member",
      "contact_id": "contact_123",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "added": 0
}

Add a contact to a static segment, referenced by contact id or email (contact), or many at once: contact_ids or emails, up to 1,000 in one call. Send exactly one of the three. The operation is idempotent — adding a contact that's already a member is a no-op that keeps its per-segment subscription and still succeeds. Each contact that joins gets a segment.joined webhook and an activity row. A list is checked first: the first contact that isn't one of yours is a 404 naming it (details), and nobody is added. One contact answers 201 with its membership; a list answers 200 with each listed contact's membership in the order sent and added, how many joined now. Adding a list counts against a limit of 30 bulk contact edits a minute per workspace by default (a 429 added nobody; retry after Retry-After). For more than 1,000 contacts, call it once per 1,000. See the current members with List segment members. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body4 fields
FieldTypeDescription
contactstringOne contact: its id (`con_…`) or email.
contact_idsstring[]Many contacts of this workspace by id (`con_…`), up to 1,000.
emailsstring[]Many contacts of this workspace by email address, up to 1,000.
subscribedbooleanA new member's per-segment subscription (default true). A contact that is already a member keeps its own.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200201401404422429

Opt a member in or out

PATCH/api/v1/segments/{id}/contacts/{contact}

PATCH /segments/{id}/contacts/{contact}
curl -X PATCH 'https://www.unitpost.com/api/v1/segments/seg_123/contacts/con_456' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscribed": false
  }'
Response · 200
{
  "object": "segment_member",
  "contact_id": "contact_123",
  "subscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z"
}

Opt a member out of this segment's sends without removing it (subscribed: false), or back in, as the members table's toggle and the preference page do. It stays a member. A dynamic segment has no per-segment opt-out (422). Requires the segments:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
contactrequiredstring · pathA contact id or email.
Request body1 field
FieldTypeDescription
subscribedrequiredboolean`false` opts the contact out of this segment's sends without removing it; `true` opts it back in.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200400401403404422

Remove a member

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

DELETE /segments/{id}/contacts/{contact}
curl -X DELETE 'https://www.unitpost.com/api/v1/segments/seg_123/contacts/con_456' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

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. Requires the segments:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
contactrequiredstring · pathA contact id or email.
204401404

Preview a filter

POST/api/v1/segments/preview

POST /segments/preview
curl -X POST 'https://www.unitpost.com/api/v1/segments/preview' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "match": "all",
      "conditions": [
        {
          "field": "plan",
          "operator": "eq",
          "value": "pro"
        }
      ]
    }
  }'
Response · 200
{
  "object": "segment_preview",
  "segment_id": "segment_123",
  "archived": false,
  "member_count": 1,
  "subscribed_count": 1,
  "sample": [
    {
      "id": "id_123",
      "email": "customer@example.com",
      "first_name": "string",
      "last_name": "string"
    }
  ]
}

Count an unsaved dynamic filter before you create the segment, as the segment dialog's live count does: how many contacts match, how many of them a campaign would mail, and a sample (which also needs contacts:read). It reads with the same filter builder the send uses. Nothing is saved. Requires the segments:read capability.

Request body1 field
FieldTypeDescription
filterrequiredobjectThe filter to count, as a dynamic segment's `filter`. Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
segment_idrequiredstring | nullThe saved segment, or null for an unsaved filter.
archivedrequiredboolean | nullWhether the saved segment is archived (a campaign can't target it); null for an unsaved filter.
member_countrequiredintegerContacts that match (or are members).
subscribed_countrequiredintegerOf those, the ones a campaign would mail: not unsubscribed. 0 means an empty send.
samplerequiredobject[]Up to 3 of the subscribed set. Empty without `contacts:read`.
200400401403422

Preview a segment

GET/api/v1/segments/{id}/preview

GET /segments/{id}/preview
curl -X GET 'https://www.unitpost.com/api/v1/segments/seg_123/preview' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "segment_preview",
  "segment_id": "segment_123",
  "archived": false,
  "member_count": 1,
  "subscribed_count": 1,
  "sample": [
    {
      "id": "id_123",
      "email": "customer@example.com",
      "first_name": "string",
      "last_name": "string"
    }
  ]
}

How many contacts a saved segment reaches: its members, the subscribed set a campaign would mail (0 means a campaign would send nothing), and a sample (which also needs contacts:read). Requires the segments:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
segment_idrequiredstring | nullThe saved segment, or null for an unsaved filter.
archivedrequiredboolean | nullWhether the saved segment is archived (a campaign can't target it); null for an unsaved filter.
member_countrequiredintegerContacts that match (or are members).
subscribed_countrequiredintegerOf those, the ones a campaign would mail: not unsubscribed. 0 means an empty send.
samplerequiredobject[]Up to 3 of the subscribed set. Empty without `contacts:read`.
200401403404422

Get the all-contacts segment

POST/api/v1/segments/all-contacts

POST /segments/all-contacts
curl -X POST 'https://www.unitpost.com/api/v1/segments/all-contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

The workspace's managed "All subscribed contacts" segment, made the first time it's asked for: the dashboard's "Everyone subscribed" campaign target. Repeating the call returns the same segment. Takes no body. Requires the segments:write capability.

Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200201400401403409422

Search docs and guides

Search the docs and product guides.