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

# Preview a segment expression.

`POST /segments/preview`

## Request

- Base URL: `https://api.maildroppa.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.maildroppa.com/segments/preview`
- Auth: API key in header `X-API-Key`

Counts proven matches and unknown results, lists the first 25 matching contacts and the contacts currently reachable (confirmed; subscribed to the optional topic). Purchase conditions report the captured order period of every source they read. Preview and stored evaluation share the same compiled predicate.

## Query parameters

- `topicId` string, uuid

## Request body

- SegmentExpression
  - `conditionGroups` SegmentConditionGroup[]
    - `conditions` SegmentCondition[]
      - `subjectType` 'FIELD' | 'TAGS' | 'TOPICS' | 'SEGMENT' | 'PURCHASES'
      - `fieldRef` SubscriberFilterFieldRef
      - `operator` 'RESPONDED_WITHIN_DAYS' | 'NO_RESPONSE_FOR_DAYS' | 'DELIVERED_WITHOUT_RESPONSE_AT_LEAST' | 'TEXT_EQUALS' | 'TEXT_NOT_EQUALS' | 'TEXT_EQUALS_IGNORE_CASE' | 'TEXT_STARTS_WITH' | 'TEXT_ENDS_WITH' | 'TEXT_CONTAINS' | 'NUMBER_EQUALS' | 'NUMBER_NOT_EQUALS' | 'NUMBER_GREATER_THAN' | 'NUMBER_LESS_THAN' | 'NUMBER_GREATER_OR_EQUAL' | 'NUMBER_LESS_OR_EQUAL' | 'DATE_EQUALS' | 'DATE_NOT_EQUALS' | 'DATE_BEFORE' | 'DATE_AFTER' | 'DATE_BEFORE_OR_EQUAL' | 'DATE_EQUAL_OR_AFTER' | 'BOOLEAN_IS_TRUE' | 'BOOLEAN_IS_FALSE' | 'OPTION_IS_ANY_OF' | 'OPTION_IS_NONE_OF' | 'OPTION_CONTAINS_ANY' | 'OPTION_CONTAINS_NONE' | 'TOPIC_OPTED_OUT' | 'CONTAINED_IN' | 'NOT_CONTAINED_IN' | 'IS_EMPTY' | 'IS_NOT_EMPTY' | 'PURCHASED' | 'NOT_PURCHASED' | 'PURCHASE_COUNT_AT_LEAST' | 'PURCHASE_COUNT_AT_MOST' | 'PURCHASE_COUNT_EQUALS' | 'FIRST_PURCHASE_IN_PERIOD' | 'LAST_PURCHASE_IN_PERIOD' | 'LAST_PURCHASE_BEFORE_PERIOD' | 'ORDER_VALUE_AT_LEAST' | 'ORDER_VALUE_AT_MOST' | 'COUPON_USED'
      - `operand` SegmentOperand
        - `kind` 'NONE' | 'TEXT' | 'NUMBER' | 'DATE' | 'OPTIONS' | 'SEGMENT' | 'PURCHASE'
        - `text` string
        - `number` number
        - `date` string, date
        - `optionIds` string[]
        - `segmentId` string, uuid
        - `purchase` PurchaseSegmentCondition
          - `sourceId` string, uuid
          - `scopeKind` 'ALL_PRODUCTS' | 'PRODUCTS' | 'VARIANTS' | 'GROUP'
          - `products` PurchaseSegmentProduct[]
            - `productId` string
            - `variantId` string
          - `groupId` string
          - `period` PurchaseSegmentPeriod
            - `kind` 'LAST_DAYS' | 'DATE_RANGE'
            - `days` integer
            - `from` string, date
            - `to` string, date
          - `count` integer
          - `currency` string
          - `amount` number
          - `couponCode` string
          - `timeZoneId` string

## Response `200`

Preview computed.

- SegmentPreview: Matches, unknown results, reachable contacts and capture scope of an expression.
  - `matchingCount` integer: Contacts proven to match the expression.
  - `unknownCount` integer: Contacts whose purchase facts are still unknown for this expression.
  - `reachableCount` integer: Matching contacts that are confirmed and, if a topic is given, subscribed to it.
  - `contacts` SegmentPreviewContactDto[]: The first 25 matching contacts.
    - `id` string, uuid
    - `email` string
    - `firstName` string
    - `subscriberStatus` string
  - `captureScopes` PurchaseCaptureScopeDto[]: Captured order periods of the purchase sources the expression reads.
    - `sourceId` string, uuid
    - `sourceName` string
    - `timeZone` string
    - `capturedOrdersFromUtc` string, date-time
    - `capturedOrdersToUtc` string, date-time
    - `baselineOpen` boolean
    - `attributionStartedAtUtc` string, date-time

## Other responses

- `400`: Bad Request
- `401`: Not Authorized
- `403`: Not Allowed
- `428`: Accept the customer agreements in the app before using API keys.

---

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