Sign in

v1

latestOpenAPI 3.0.32026-07-26737274.2 KB
Subscribers

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

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: Starting October 15, 2026, 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 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.

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