---
title: "Retrieve subscribers matching a segment expression"
method: POST
path: "/subscribers/filtered"
tags: ["Subscribers"]
---

# Retrieve subscribers matching a segment expression

`POST /subscribers/filtered`

## 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/subscribers/filtered`
- Auth: API key in header `X-API-Key`

Applies the current SegmentExpression condition-group model with status and pagination options. Conditions inside one group use AND; groups use OR. Field conditions use subjectType FIELD with fieldRef. Tag conditions use subjectType TAGS and tag IDs in operand.optionIds. Nested segment conditions use subjectType SEGMENT and operand.segmentId.

## Query parameters

- `pageNumber` integer
- `pageSize` integer
- `status` string

## Request body

- object: SegmentExpression to apply directly to subscribers.
  - `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`

Subscribers retrieved successfully.

- PaginatedSubscribersDto: Paginated response containing SubscriberDto items.
  - `items` SubscriberOverview[]: The items on the current page.
    - `id` string, uuid
    - `email` string: Subscriber email address.
    - `firstName` string: Subscriber first name, if present.
    - `subscriberStatus` 'PENDING' | 'CONFIRMED' | 'UNSUBSCRIBED' | 'COLD' | 'BOUNCED' | 'SOFT_BOUNCED' | 'BLOCKED' | 'DELETED'
    - `registeredAt` string: Registration date/time of the subscriber.
    - `lastImportedAtUtc` string, date-time
    - `tags` string[]: List of tag identifiers associated with the subscriber.
    - `visibleFieldValues` SubscriberFieldValue[]: Visible subscriber field display values for the list view.
      - `id` string, uuid
      - `personalizationTagName` string: Stable subscriber personalization tag name returned in the personalizationTagName property.
      - `value` string: Display value for this field. Choice and multi-select values are returned as labels for display; use subscriber field value endpoints for typed option IDs.
  - `pageNumber` integer: Which page is this (1-based index)?
  - `pageSize` integer: Number of items per page.
  - `totalItems` integer: Total number of items matching the query.
  - `totalPages` integer: Total number of pages based on page size.
  - `statusCounts` SubscriberStatusCountsDto: Account-wide counts, independent of search, status filter and pagination. All includes every subscriber status.
    - `all` integer
    - `confirmed` integer
    - `pending` integer
    - `unsubscribed` integer

## 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)