KIkit
Subscribers

Filter subscribers by engagement, sign-up date, state, and tags

Changed on

Searches your subscriber list with compound conditions: email engagement (opens, clicks, sends, deliveries — with count thresholds and date ranges), sign-up date, subscriber state, and tags. Every condition in the all array must match (AND logic).

Use counting_mode to control how engagement thresholds are tallied — raw (default) counts every event, unique_email counts distinct emails — and the include array to embed extra fields (tags, stats, custom fields, location, attribution, canceled_at) on each returned subscriber.

Data retention: Email stats (opens, clicks, sends, bounces, and unsubscribes) are available via the API for the last 5 years — engagement-condition date bounds are clamped to that window, and a stats include range outside it returns a 400 error. See Email data retention for the full policy.

post/v4/subscribers/filter

Request

  • Base URL
    https://api.kit.com
  • URL
    https://api.kit.com/v4/subscribers/filter
  • Auth
    • API key in header X-Kit-Api-Key
    • or OAuth 2
      Authorization code: https://api.kit.com/v4/oauth/authorize
      Token URL: https://api.kit.com/v4/oauth/token

Request body

counting_mode'raw' | 'unique_email'

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.

sort_field'id' | 'first_name' | 'email_address' | 'created_at' | 'engagement__sent' | 'engagement__opens' | 'engagement__clicks' | 'engagement__open_rate' | 'engagement__click_rate' | 'location__distance'

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.

sort_order'asc' | 'desc'

Sort direction (default: desc).

Example request

{
  "include": [
    {
      "type": "tags"
    },
    {
      "type": "stats",
      "range": {
        "start": "2026-05-01",
        "end": "2026-06-30"
      }
    }
  ]
}

Response

Returns a list of subscribers matching the filters

Changes

  • f04308f83b63Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property