Filter subscribers

kit.filterSubscribers filters subscribers by engagement, sign-up, state, and tags.

automations/filter-subscribers.automation.ts

import { automation, markSignificant } from "automate.ax"
import { kit } from "automate.ax/kit"

export default automation("Filter subscribers", () => {
  markSignificant(
    kit.filterSubscribers({
      countingMode: "unique_email",
      all: [
        {
          type: "opens",
          countGreaterThanOrEqual: 2,
          after: "2026-08-01",
        },
        {
          type: "attribution",
          any: [
            {
              type: "kit_source",
              sourceType: "api_subscription",
            },
          ],
        },
      ],
      include: [{ type: "tags" }],
      sortField: "engagement__open_rate",
      sortOrder: "desc",
    }),
  )
})

Input

Pass these fields:

Field	Type	Required	Description
`countingMode`	`"raw" \| "unique_email"`	No	Controls how engagement-filter count thresholds are tallied. `raw` (default) counts every event—five opens of the same email = five. `unique_email` counts distinct emails on which the action occurred—five opens of the same email = one. Applies to every engagement filter (opens, clicks, sent, delivered) in the request; ignored for other filter types.
`all`	`FilterCondition[]`	Yes	Conditions that every returned subscriber must match.
`include`	`object[]`	No	Optional. Array of `{ type, ...config }` objects naming additional fields to embed on each subscriber row. Valid types: `attribution`, `tags`, `location`, `canceled_at`, `stats`, `custom_fields`. The `stats` type accepts an optional `range: { start, end }` (YYYY-MM-DD dates, defaulting to the last 90 days). The `custom_fields` type adds a `fields` object with all account custom field values (null for fields the subscriber has not set).
`sortField`	`"id" \| "first_name" \| "email_address" \| "created_at" \| "engagement__sent" \| "engagement__opens" \| "engagement__clicks" \| "engagement__open_rate" \| "engagement__click_rate" \| "location__distance"`	No	Field to order results by. Base columns (`id`, `first_name`, `email_address`, `created_at`) order by that subscriber attribute. `engagement__<metric>` orders by an engagement stat over the trailing 90 days: counts (`sent`, `opens`, `clicks`) and rates (`open_rate`, `click_rate`); subscribers with no sends order as 0. `location__distance` orders by great-circle distance and requires a `location` filter in the same request—its `latitude`/`longitude` supply the origin, and subscribers without a primary location are excluded. Distance defaults to nearest-first (`sort_order` defaults to `asc` for this field); pass `sort_order=desc` for farthest-first. Default: `created_at`.
`sortOrder`	`"asc" \| "desc"`	No	Sort direction (default: desc).

Each filter condition requires type. Engagement conditions (opens, clicks, sent, or delivered) accept countGreaterThan, countGreaterThanOrEqual, countLessThan, countLessThanOrEqual, after, and before. A subscriber_state condition accepts states; a custom_field condition accepts subscriberCustomFieldId, value, and comparison; and a location condition requires latitude, longitude, and radius. Some conditions accept an any array:

Engagement conditions accept { type: "broadcasts", ids } or { type: "urls", urls, matching }.
A tags condition accepts { type: "ids", matching }.
An attribution condition accepts { type: "forms", ids } or { type: "kit_source", sourceType?, sourceIds?, sourceNames?, mechanism?, mechanismIds? }.

Output

Returns an object with these fields:

Field	Type	Required	Description
`subscribers`	`object[]`	Yes	—
`pagination`	`object`	Yes	—

Kit list and reporting endpoints can lag recent writes. Cursor-based list actions accept after or before; perPage defaults to Kit’s provider default and cannot exceed 1,000. Kit rate limits OAuth connections to 600 requests per 60 seconds and V4 API keys to 120 requests per 60 seconds. Automate.ax honors provider retry timing for rate-limit and temporary bulk-capacity responses.

Built-in triggers

Built-in actions

Runtime utilities

Integrations

Input

Output

​Input

​Output

Input

Output