KIkit
Subscribers

List subscribers

Changed on

Returns a cursor-paginated list of subscribers in the account. By default only active subscribers are returned — use status (active, inactive, bounced, complained, cancelled, or all) to widen the search. Look a subscriber up by exact email_address, filter by created_after/created_before and updated_after/updated_before, and order with sort_field (id, created_at, updated_at, cancelled_at, or an engagement__<metric>) and sort_order.

Use include (comma-separated: attribution, tags, location, canceled_at) to embed extra fields on each subscriber — including canceled_at without status=cancelled returns a 422. Set slim=true to omit the fields object (custom field values) for a faster, smaller response.

Ordering by an engagement metric (opens, clicks, sends over the trailing 90 days) is supported here via sort_field=engagement__<metric>, but cannot be combined with an email_address filter. To filter subscribers by engagement, use Filter subscribers by engagement instead.

Results are eventually consistent and may briefly lag very recent changes — see Eventual consistency.

get/v4/subscribers

Request

  • Base URL
    https://api.kit.com
  • URL
    https://api.kit.com/v4/subscribers
  • 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

Query parameters

afterstring nullable

To fetch next page of results, use ?after=<end_cursor>

beforestring nullable

To fetch previous page of results, use ?before=<start_cursor>

created_afterstring

Filter subscribers who have been created after this date (format yyyy-mm-dd)

created_beforestring

Filter subscribers who have been created before this date (format yyyy-mm-dd)

email_addressstring
includestring

Comma-separated list of additional fields to include on each subscriber. Valid options: attribution, tags, location, canceled_at. canceled_at may only be used together with status=cancelled.

include_total_countboolean

Set to true to include the total_count in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.

per_pagenumber nullable

Number of results per page. Default 500, maximum 1000.

slimboolean

When true, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed.

sort_field'id' | 'created_at' | 'updated_at' | 'cancelled_at' | 'canceled_at' | 'engagement__sent' | 'engagement__opens' | 'engagement__clicks' | 'engagement__open_rate' | 'engagement__click_rate'

Field to order by. id (default), created_at, or updated_at order by that subscriber attribute. cancelled_at (alias canceled_at) orders by cancellation date and requires status=cancelled. 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. Engagement sorts cannot be combined with an email_address filter.

sort_order'asc' | 'desc'
status'active' | 'inactive' | 'bounced' | 'complained' | 'cancelled' | 'all'

Filter subscribers who have this status (active, inactive, bounced, complained, cancelled or all). Defaults to active.

updated_afterstring

Filter subscribers who have been updated after this date (format yyyy-mm-dd)

updated_beforestring

Filter subscribers who have been updated before this date (format yyyy-mm-dd)

Response

Returns subscriber attribution, tags, and primary location when requested via the include param

Changes

  • f04308f83b63Revision changes
    • breaking

      the query request parameter sort_field was restricted to a list of enum values

    • info

      added the new enum value canceled_at to the query request parameter sort_field

    • info

      added the new enum value cancelled_at to the query request parameter sort_field

    • info

      added the new enum value created_at to the query request parameter sort_field

    • info

      added the new enum value engagement__click_rate to the query request parameter sort_field

    • info

      added the new enum value engagement__clicks to the query request parameter sort_field

    • info

      added the new enum value engagement__open_rate to the query request parameter sort_field

    • info

      added the new enum value engagement__opens to the query request parameter sort_field

    • info

      added the new enum value engagement__sent to the query request parameter sort_field

    • info

      added the new enum value id to the query request parameter sort_field

    • info

      added the new enum value updated_at to the query request parameter sort_field