---
title: "Preview a segment definition"
method: POST
path: "/v1/segments/preview"
tags: ["Segments"]
---

# Preview a segment definition

`POST /v1/segments/preview`

## Request

- Base URL: `https://api.mailrith.com`
- URL: `https://api.mailrith.com/v1/segments/preview`
- Auth: HTTP bearer

Returns subscriber counts for an unsaved segment definition. Include `current_segment_id` when previewing edits to an existing segment so circular segment references are rejected before saving.

## Request body

- SegmentPreviewRequest
  - `definition` AudienceDefinition, required
    - `match` 'all' | 'any', required
    - `groups` AudienceConditionGroup[], required
      - `id` string, required
      - `match` 'all' | 'any', required
      - `conditions` AudienceCondition[], required
        - `id` string, required
        - `field` 'subscriber_status' | 'country' | 'segment' | 'tag' | 'sequence' | 'form' | 'custom_field' | 'email_opened' | 'email_unsubscribed' | 'magic_link_clicked', required
        - `operator` 'is' | 'is_not' | 'has_any_of' | 'has_none_of' | 'is_active_in_any_of' | 'is_not_active_in_any_of' | 'has_completed_any_of' | 'has_not_completed_any_of' | 'has_ever_been_in_any_of' | 'has_never_been_in_any_of' | 'contains' | 'does_not_contain' | 'is_empty' | 'is_not_empty' | 'before' | 'after' | 'on' | 'in_last_days' | 'greater_than' | 'less_than' | 'in_region' | 'not_in_region', required
        - `value` union
          - string
          - number
          - boolean
          - string[]
        - `customFieldId` string, nullable
  - `current_segment_id` string, nullable: When previewing an edit to an existing segment, include that segment id so Mailrith can catch circular segment references before saving.

## Response `200`

The preview counts were returned.

- object
  - `data` SegmentPreview, required
    - `confirmed_subscriber_count` integer, required
    - `total_subscriber_count` integer, required

## Other responses

- `400`: The request is invalid.

---

[API](https://skmtc.dev/mailrith/apis/mailrith-api.md) · [All operations](https://skmtc.dev/mailrith/apis/mailrith-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailrith/apis/mailrith-api/revisions/41f09536f2da?raw)