openapi: 3.0.3 info: title: Kit Accounts Subscribers API version: '4.0' servers: - url: https://api.kit.com tags: - name: Subscribers paths: /v4/bulk/subscribers: post: summary: Bulk create subscribers description: See "[Bulk & async processing](#bulk-amp-async-processing)" for more information. tags: - Subscribers security: - OAuth2: [] parameters: [] responses: '200': description: Creates or updates the subscribers synchronously when 100 or less subscribers are requested content: application/json: schema: type: object properties: subscribers: type: array items: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string required: - id - first_name - email_address - state - created_at failures: type: array items: type: object properties: subscriber: type: object properties: first_name: type: string email_address: type: string nullable: true state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string nullable: true required: - first_name - email_address - state - created_at errors: type: array items: type: string required: - subscriber - errors required: - subscribers - failures example: subscribers: - id: 596 first_name: null email_address: brooke@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' - id: 597 first_name: Camille email_address: camille@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' - id: 595 first_name: Alice email_address: alice@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' failures: - subscriber: first_name: Benito email_address: null state: active created_at: null errors: - Email address is invalid '202': description: Creates or updates subscribers asynchronously when more than 100 subscribers are requested content: application/json: schema: type: object properties: {} example: {} '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '403': description: Returns a 403 when the number of subscribers in the request would exceed the account's subscriber limit content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - This request would exceed your subscriber limit '413': description: Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later. '422': description: Returns a 422 when `subscribers` is empty or not an array content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - No subscribers included for processing requestBody: content: application/json: schema: type: object properties: subscribers: type: array items: type: object properties: first_name: type: string nullable: true email_address: type: string nullable: true state: type: string nullable: true enum: - active - cancelled - bounced - complained - inactive callback_url: type: string nullable: true required: - subscribers example: subscribers: - first_name: Test Subscriber 0 email_address: subscriber_0@convertkit.dev - first_name: Test Subscriber 1 email_address: subscriber_1@convertkit.dev - first_name: Test Subscriber 2 email_address: subscriber_2@convertkit.dev - first_name: Test Subscriber 3 email_address: subscriber_3@convertkit.dev callback_url: null /v4/subscribers: get: summary: List subscribers tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: - name: after description: To fetch next page of results, use `?after=` in: query required: false schema: type: string nullable: true - name: before description: To fetch previous page of results, use `?before=` in: query required: false schema: type: string nullable: true - name: created_after description: Filter subscribers who have been created after this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-01-17T11:43:55Z' - name: created_before description: Filter subscribers who have been created before this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-02-18T11:43:55Z' - name: email_address in: query required: false schema: type: string example: subscriber89@kit.dev,subscriber90@kit.dev,subscriber91@kit.dev - name: include in: query required: false schema: type: string example: attribution,tags,location description: '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`.' - name: include_total_count description: 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. in: query required: false schema: type: boolean example: false - name: per_page description: Number of results per page. Default 500, maximum 1000. in: query required: false schema: type: number nullable: true example: 10 - name: slim in: query required: false schema: type: boolean example: false description: When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed. - name: sort_field in: query required: false schema: type: string example: cancelled_at - name: sort_order in: query required: false schema: type: string enum: - asc - desc example: asc - name: status description: Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`. in: query required: false schema: type: string enum: - active - inactive - bounced - complained - cancelled - all example: bounced - name: updated_after description: Filter subscribers who have been updated after this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-01-17T11:43:55Z' - name: updated_before description: Filter subscribers who have been updated before this date (format yyyy-mm-dd) in: query required: false schema: type: string example: '2023-02-18T11:43:55Z' responses: '200': description: Returns subscriber attribution, tags, and primary location when requested via the include param content: application/json: schema: type: object properties: subscribers: type: array items: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object properties: category: type: string nullable: true attribution: type: object description: Returned when `include` contains `attribution`. nullable: true properties: referrer: type: string nullable: true utm_source: type: string nullable: true utm_medium: type: string nullable: true utm_campaign: type: string nullable: true utm_term: type: string nullable: true utm_content: type: string nullable: true source_type: type: string nullable: true source_name: type: string nullable: true source_mechanism: type: string nullable: true source_mechanism_id: type: integer nullable: true required: - referrer - utm_source - utm_medium - utm_campaign - utm_term - utm_content - source_type - source_name - source_mechanism - source_mechanism_id tags: type: array description: Returned when `include` contains `tags`. items: type: object properties: id: type: integer nullable: true name: type: string nullable: true location: type: object description: Returned when `include` contains `location`. nullable: true properties: city: type: string nullable: true state: type: string nullable: true country: type: string nullable: true latitude: type: number nullable: true format: float longitude: type: number nullable: true format: float timezone: type: string nullable: true required: - city - state - country - latitude - longitude - timezone canceled_at: type: string format: date-time nullable: true description: Returned when `include` contains `canceled_at`. Requires `status=cancelled`. required: - id - state - first_name - email_address - created_at - fields pagination: type: object properties: has_previous_page: type: boolean has_next_page: type: boolean start_cursor: type: string end_cursor: type: string per_page: type: integer required: - has_previous_page - has_next_page - start_cursor - end_cursor - per_page required: - subscribers - pagination example: subscribers: - id: 200 state: active first_name: Alice email_address: alice@convertkit.dev created_at: '2023-01-27T11:43:55Z' fields: category: One attribution: referrer: https://t.co/abc123 utm_source: twitter utm_medium: cpc utm_campaign: spring_launch utm_term: newsletter+for+creators utm_content: hero_cta source_type: form_subscription source_name: Welcome Form source_mechanism: landing_page source_mechanism_id: null tags: - id: 1 name: VIP location: city: Portland state: OR country: US latitude: 45.5 longitude: -122.6 timezone: America/Los_Angeles - id: 201 state: active first_name: Benito email_address: benito@convertkit.dev created_at: '2023-02-03T11:43:55Z' fields: {} attribution: referrer: https://creator.kit.com/jane-smith utm_source: kit utm_medium: referral utm_campaign: null utm_term: null utm_content: null source_type: form_subscription source_name: Jane Smith's Recommendations source_mechanism: recommendations source_mechanism_id: null tags: - id: 2 name: Newsletter location: city: Austin state: TX country: US latitude: 30.27 longitude: -97.74 timezone: America/Chicago - id: 202 state: active first_name: Camille email_address: camille@convertkit.dev created_at: '2023-02-10T11:43:55Z' fields: {} attribution: referrer: null utm_source: null utm_medium: null utm_campaign: null utm_term: null utm_content: null source_type: api_subscription source_name: Partner Integration source_mechanism: api source_mechanism_id: 12345 tags: [] location: null - id: 203 state: active first_name: Elliot email_address: elliot@convertkit.dev created_at: '2023-02-13T11:43:55Z' fields: {} attribution: referrer: null utm_source: null utm_medium: null utm_campaign: null utm_term: null utm_content: null source_type: null source_name: null source_mechanism: null source_mechanism_id: null tags: - id: 3 name: Imported location: city: null state: null country: null latitude: null longitude: null timezone: null pagination: has_previous_page: false has_next_page: false start_cursor: MjAyMy0wMS0yNyAxMTo0Mzo1NSBVVEM= end_cursor: MjAyMy0wMi0xMyAxMTo0Mzo1NSBVVEM= per_page: 500 '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '422': description: raises an error when sorting on cancelled_at without the cancelled status content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The status param must be `cancelled` if sort_field is `cancelled_at` x-mcp: enabled: true post: summary: Create a subscriber description: Behaves as an upsert. If a subscriber with the provided email address does not exist, it creates one with the specified first name and state. If a subscriber with the provided email address already exists, it updates the first name.

If you include a custom field key that does not exist on your account, the request returns an error. Use [List custom fields](/api-reference/custom-fields/list-custom-fields) to retrieve existing keys, or [Create a custom field](/api-reference/custom-fields/create-a-custom-field) to add new fields before setting them for subscribers.

NOTE: Updating the subscriber state with this endpoint is not supported at this time.
NOTE: We support creating/updating a maximum of 140 custom fields at a time. tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: [] responses: '200': description: Returns a 200 and updates the subscriber first name when a subscriber with provided email already exists content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object properties: {} required: - id - first_name - email_address - state - created_at - fields required: - subscriber example: subscriber: id: 353 first_name: Alice email_address: alice@convertkit.dev state: inactive created_at: '2023-02-17T11:43:55Z' fields: {} '201': description: Creates a new subscriber content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object additionalProperties: type: string description: Custom field values for the subscriber, keyed by the custom field's `key`. required: - id - first_name - email_address - state - created_at - fields warnings: type: array items: type: string description: Present only when the request referenced custom field keys that don't exist on the account. Each entry names an unknown key that was ignored; the subscriber is still created or updated. required: - subscriber example: subscriber: id: 349 first_name: Alice email_address: alice@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' fields: birthday: Feb 17 last_name: Lamarr source: landing page '202': description: Returns a 202 and asynchronously adds custom fields for the new subscriber when more than 10 custom fields are included in the request content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object properties: company: nullable: true coupon: nullable: true enrolled_in_coaching: nullable: true how_did_you_hear_about_us: nullable: true interests: nullable: true lead_score: nullable: true phone_number: nullable: true postal_code: nullable: true role: nullable: true social_media: nullable: true website: nullable: true required: - company - coupon - enrolled_in_coaching - how_did_you_hear_about_us - interests - lead_score - phone_number - postal_code - role - social_media - website required: - id - first_name - email_address - state - created_at - fields required: - subscriber example: subscriber: id: 351 first_name: Alice email_address: alice@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' fields: company: null coupon: null enrolled_in_coaching: null how_did_you_hear_about_us: null interests: null lead_score: null phone_number: null postal_code: null role: null social_media: null website: null '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '422': description: Returns a 422 with an error message when one or more of the parameters are invalid content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Email address is invalid requestBody: content: application/json: schema: type: object properties: first_name: type: string nullable: true email_address: type: string state: type: string nullable: true enum: - active - cancelled - bounced - complained - inactive description: Create subscriber in this state (`active`, `bounced`, `cancelled`, `complained` or `inactive`). Defaults to `active`. fields: type: object additionalProperties: type: string description: Custom field values keyed by the custom field's `key` (e.g. `last_name`, not `Last Name`). Unknown keys are ignored and reported in the response `warnings` array. required: - email_address example: first_name: Alice email_address: alice@convertkit.dev state: active fields: last_name: Lamarr birthday: Feb 17 source: landing page role: Software developer company: Convertkit postal_code: '83702' website: convertkit.com social_media: https://www.linkedin.com/company/convertkit how_did_you_hear_about_us: Social media interests: Monetization coupon: '' phone_number: 555-555-5555 enrolled_in_coaching: 'true' lead_score: '87' x-mcp: enabled: true /v4/subscribers/filter: post: summary: Filter subscribers based on engagement tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: [] responses: '200': description: Returns a list of subscribers matching the filters content: application/json: schema: type: object properties: subscribers: type: array items: type: object properties: id: type: string first_name: type: string nullable: true email_address: type: string created_at: type: string tag_names: type: array items: type: string tag_ids: type: array items: type: string required: - id - first_name - email_address - created_at pagination: type: object properties: has_previous_page: type: boolean has_next_page: type: boolean start_cursor: type: string end_cursor: type: string per_page: type: integer total_count: type: integer required: - has_previous_page - has_next_page - start_cursor - end_cursor - per_page required: - subscribers - pagination example: subscribers: - id: '456' first_name: Jane email_address: jane@example.com created_at: '2024-12-01T15:45:00Z' tag_names: - newsletter - engaged tag_ids: - '123' - '456' - id: '789' first_name: null email_address: anonymous@example.com created_at: '2024-11-15T10:00:00Z' tag_names: [] tag_ids: [] pagination: has_previous_page: false has_next_page: true start_cursor: WzQ1Nl0= end_cursor: Wzc4OV0= per_page: 10 total_count: 42 '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid requestBody: content: application/json: schema: $ref: '#/components/schemas/SubscriberFilterRequest' example: all: - type: opens count_greater_than: 5 after: '2024-01-01' before: '2024-12-31' - type: clicks count_greater_than: 2 after: '2024-01-01' before: '2024-12-31' any: - type: urls urls: - kit.com - amazon.com matching: contains - type: broadcasts ids: - 1 - 2 - 3 - type: tags any: - type: ids matching: - 123 - 456 - type: attribution any: - type: forms ids: - 789 - 1001 x-mcp: enabled: true /v4/subscribers/{id}: get: summary: Get a subscriber tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: - name: id in: path required: true schema: type: integer example: 325 responses: '200': description: Returns the subscriber details content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object properties: category: type: string required: - category canceled_at: type: string nullable: true required: - id - first_name - email_address - state - created_at - fields required: - subscriber example: subscriber: id: 324 first_name: Alice email_address: alice@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' fields: category: One canceled_at: null '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '404': description: Returns a 404 when the provided id does not exist content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Not Found x-mcp: enabled: true put: summary: Update a subscriber description: If you include a custom field key that does not exist on your account, the request returns an error. Use [List custom fields](/api-reference/custom-fields/list-custom-fields) to retrieve existing keys, or [Create a custom field](/api-reference/custom-fields/create-a-custom-field) to add new fields before setting them for subscribers.

NOTE: We support creating/updating a maximum of 140 custom fields at a time. tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: - name: id in: path required: true schema: type: integer example: 387 responses: '200': description: Updates the subscriber's email address and first name content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object additionalProperties: type: string description: Custom field values for the subscriber, keyed by the custom field's `key`. required: - id - first_name - email_address - state - created_at - fields warnings: type: array items: type: string description: Present only when the request referenced custom field keys that don't exist on the account. Each entry names an unknown key that was ignored; the subscriber is still created or updated. required: - subscriber example: subscriber: id: 378 first_name: Alice email_address: alice@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' fields: birthday: Feb 17 last_name: Lamarr source: landing page '202': description: Returns a 202 and asynchronously updates custom fields for the subscriber when more than 10 custom fields are included in the request content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer first_name: type: string nullable: true email_address: type: string state: type: string enum: - active - cancelled - bounced - complained - inactive created_at: type: string fields: type: object properties: birthday: nullable: true company: nullable: true coupon: nullable: true how_did_you_hear_about_us: nullable: true interests: nullable: true last_name: nullable: true postal_code: nullable: true role: nullable: true social_media: nullable: true source: nullable: true website: nullable: true required: - birthday - company - coupon - how_did_you_hear_about_us - interests - last_name - postal_code - role - social_media - source - website required: - id - first_name - email_address - state - created_at - fields required: - subscriber example: subscriber: id: 380 first_name: Alice email_address: alice@convertkit.dev state: active created_at: '2023-02-17T11:43:55Z' fields: birthday: null company: null coupon: null how_did_you_hear_about_us: null interests: null last_name: null postal_code: null role: null social_media: null source: null website: null '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '404': description: Returns a 404 when the provided id does not exist content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Not Found '422': description: Returns 422 with an error when email address is already in use content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Email address has already been taken requestBody: content: application/json: schema: type: object properties: first_name: type: string nullable: true email_address: type: string fields: type: object additionalProperties: type: string description: Custom field values keyed by the custom field's `key` (e.g. `last_name`, not `Last Name`). Unknown keys are ignored and reported in the response `warnings` array. required: - email_address example: first_name: Alice email_address: alice@convertkit.dev fields: last_name: Lamarr birthday: Feb 17 source: landing page role: Software developer company: Convertkit postal_code: '83702' website: convertkit.com social_media: https://www.linkedin.com/company/convertkit how_did_you_hear_about_us: Social media interests: Monetization coupon: '' x-mcp: enabled: true /v4/subscribers/{id}/unsubscribe: post: summary: Unsubscribe subscriber tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: - name: id in: path required: true schema: type: integer example: 344 responses: '204': description: Unsubscribes the subscriber '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '404': description: Returns a 404 when the provided id does not exist content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Not Found requestBody: content: application/json: schema: type: object properties: {} example: {} x-mcp: enabled: true /v4/subscribers/{subscriber_id}/stats: get: summary: List stats for a subscriber description: 'Retrieve email stats for a specific subscriber. You can filter the stats by providing `email_sent_after` and/or `email_sent_before` query parameters to limit the stats to emails sent within a specific date range. Note: Only data for events in the last 5 years will be included.' tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: - name: email_sent_after description: 'Filter to stats for emails sent after this date (YYYY-MM-DD)/nNOTE: This will only include stats for emails sent in the last 5 years.' in: query required: false schema: type: string example: '2025-07-01' - name: email_sent_before description: 'Filter to stats for emails sent before this date (YYYY-MM-DD)/nNote: Only data for events in the last 5 years will be included.' in: query required: false schema: type: string example: '2025-08-31' - name: subscriber_id in: path required: true schema: type: integer example: 1097 responses: '200': description: Returns the stats for a subscriber content: application/json: schema: type: object properties: subscriber: type: object properties: id: type: integer stats: type: object properties: sent: type: integer opened: type: integer clicked: type: integer bounced: type: integer open_rate: type: number format: float click_rate: type: number format: float last_sent: type: string last_opened: type: string last_clicked: type: string sends_since_last_open: type: integer sends_since_last_click: type: integer required: - sent - opened - clicked - bounced - open_rate - click_rate - last_sent - last_opened - last_clicked - sends_since_last_open - sends_since_last_click required: - id - stats required: - subscriber example: subscriber: id: 1097 stats: sent: 2 opened: 1 clicked: 1 bounced: 1 open_rate: 0.5 click_rate: 0.5 last_sent: '2025-07-13T12:00:00Z' last_opened: '2025-07-13T12:00:00Z' last_clicked: '2025-07-14T12:00:00Z' sends_since_last_open: 0 sends_since_last_click: 0 '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid x-mcp: enabled: true /v4/subscribers/{subscriber_id}/tags: get: summary: List tags for a subscriber tags: - Subscribers security: - API Key: [] - OAuth2: [] parameters: - name: after description: To fetch next page of results, use `?after=` in: query required: false schema: nullable: true - name: before description: To fetch previous page of results, use `?before=` in: query required: false schema: nullable: true - name: include_total_count description: 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. in: query required: false schema: type: boolean example: false - name: per_page description: Number of results per page. Default 500, maximum 1000. in: query required: false schema: nullable: true - name: subscriber_id in: path required: true schema: type: integer example: 1131 responses: '200': description: Returns a paginated list of all tags for a subscriber content: application/json: schema: type: object properties: tags: type: array items: type: object properties: id: type: integer name: type: string tagged_at: type: string required: - id - name - tagged_at pagination: type: object properties: has_previous_page: type: boolean has_next_page: type: boolean start_cursor: type: string end_cursor: type: string per_page: type: integer required: - has_previous_page - has_next_page - start_cursor - end_cursor - per_page required: - tags - pagination example: tags: - id: 111 name: Tag B tagged_at: '2023-02-17T10:43:55Z' - id: 112 name: Tag A tagged_at: '2023-02-17T10:43:55Z' pagination: has_previous_page: false has_next_page: false start_cursor: WzExXQ== end_cursor: WzEwXQ== per_page: 500 '401': description: Returns a 401 if the token and/or account cannot be authenticated content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - The access token is invalid '404': description: Returns a 404 when the provided id does not exist content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Not Found x-mcp: enabled: true components: schemas: SubscriberFilterRequest: type: object description: Filter subscribers based on engagement and subscription criteria using the 'all' array with filter conditions that must all be met (AND logic). properties: counting_mode: type: string enum: - raw - unique_email description: 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: type: array description: Array of filter conditions where ALL must be met (AND logic) items: $ref: '#/components/schemas/FilterCondition' required: - all FilterCondition: type: object description: A filter condition with type and optional parameters. Used within the 'all' array for complex filtering where multiple conditions must be met. properties: type: type: string enum: - opens - clicks - sent - delivered - subscribed - subscriber_state - tags - attribution description: Type of filter condition. `attribution` matches subscribers by their *original signup attribution* — currently supports a `forms` sub-condition that matches by the form / landing-page id the subscriber signed up through. Attribution is the original signup source; it does not track current subscription state. count_greater_than: type: integer description: Minimum count (exclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered'). count_greater_than_or_equal: type: integer description: Minimum count (inclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered'). count_less_than: type: integer description: Maximum count (exclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered'). count_less_than_or_equal: type: integer description: Maximum count (inclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered'). after: type: string format: date description: Start date (YYYY-MM-DD). For 'subscribed' type, filters by subscriber_created_at. For engagement types, filters by event date. Not applicable for 'tags', 'subscriber_state', or 'attribution' types. before: type: string format: date description: End date (YYYY-MM-DD). For 'subscribed' type, filters by subscriber_created_at. For engagement types, filters by event date. Not applicable for 'tags', 'subscriber_state', or 'attribution' types. states: type: array items: type: string enum: - active - inactive - bounced - cancelled - complained description: Subscriber lifecycle states. Required for 'subscriber_state' type; ignored for other types. Subscribers matching any of the listed states pass the filter. Strongly recommended to use `['active']` unless you specifically need other states — most subscriber-facing queries elsewhere in the app scope to active subscribers by default. any: type: array description: Array of OR conditions. Subscriber activity must match ANY of these conditions. Engagement types accept broadcasts/URLs; 'tags' accepts tag id matchers; 'attribution' accepts attribution sub-conditions (currently 'forms'). Not applicable for 'subscribed' or 'subscriber_state' types. items: oneOf: - title: Broadcasts $ref: '#/components/schemas/BroadcastAnyCondition' - title: URLs (clicks only) $ref: '#/components/schemas/UrlAnyCondition' - title: Tag ids (tags only) $ref: '#/components/schemas/IdsAnyCondition' - title: Forms (attribution only) $ref: '#/components/schemas/FormsAnyCondition' required: - type UrlAnyCondition: type: object description: Filter by URL patterns. Only applicable for 'clicks' type. Subscriber must have clicked ANY of the specified URLs. properties: type: type: string enum: - urls description: Must be 'urls' ids: type: array items: type: integer description: Array of URL IDs. Subscriber must have clicked ANY of these. urls: type: array items: type: string description: Array of URL patterns. Subscriber must have clicked ANY of these. matching: type: string enum: - exact - contains - starts_with - ends_with description: URL matching strategy default: exact required: - type FormsAnyCondition: type: object description: 'Attribution sub-condition: matches subscribers whose original signup attribution points at one of the given form / landing-page ids. Ids may refer to either a form or a legacy landing page — the attribution source does not distinguish between the two.' properties: type: type: string enum: - forms description: Must be 'forms' ids: type: array items: type: integer description: Form / landing-page ids the subscriber's attribution should match. required: - type - ids IdsAnyCondition: type: object description: Match a list of ids. Used by the 'tags' filter to select tag ids. properties: type: type: string enum: - ids description: Must be 'ids' matching: type: array items: type: integer description: Ids the filter should match against. required: - type - matching BroadcastAnyCondition: type: object description: Filter by specific broadcast IDs. Subscriber must have interacted with ANY of the specified broadcasts. properties: type: type: string enum: - broadcasts description: Must be 'broadcasts' ids: type: array items: type: integer description: Array of broadcast IDs. Subscriber must match ANY of these. required: - type - ids securitySchemes: API Key: description: Authenticate API requests via an API Key type: apiKey in: header name: X-Kit-Api-Key OAuth2: description: Authenticate API requests via an OAuth token type: oauth2 flows: authorizationCode: authorizationUrl: https://api.kit.com/v4/oauth/authorize tokenUrl: https://api.kit.com/v4/oauth/token refreshUrl: https://api.kit.com/v4/oauth/token scopes: read: Read access to Kit API v4 write: Write access to Kit API v4 x-mint: mcp: enabled: true