openapi: 3.0.3 info: title: Kit Accounts Broadcasts API version: '4.0' servers: - url: https://api.kit.com tags: - name: Broadcasts paths: /v4/broadcasts: get: summary: List broadcasts tags: - Broadcasts 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: sent_after description: Get broadcasts sent after this date (format yyyy-mm-dd). in: query required: false schema: nullable: true - name: sent_before description: Get broadcasts sent before this date (format yyyy-mm-dd). in: query required: false schema: nullable: true - 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. responses: '200': description: Returns a paginated list of all broadcasts for your account (including draft, scheduled, and already sent) content: application/json: schema: type: object properties: broadcasts: type: array items: type: object properties: id: type: integer publication_id: type: integer description: Identifier of the underlying publication. Broadcasts that are also published as posts share the same `publication_id` — use it to match a broadcast to its post via `GET /v4/posts`. created_at: type: string subject: type: string preview_text: type: string nullable: true description: type: string nullable: true content: type: string nullable: true public: type: boolean published_at: type: string nullable: true send_at: type: string nullable: true thumbnail_alt: type: string nullable: true thumbnail_url: type: string nullable: true public_url: type: string nullable: true email_address: type: string nullable: true email_template: type: object properties: id: type: integer name: type: string required: - id - name subscriber_filter: type: array items: type: object properties: all: type: array items: type: object properties: type: type: string required: - type required: - all status: type: string required: - id - publication_id - created_at - subject - preview_text - description - public - published_at - send_at - thumbnail_alt - thumbnail_url - content - public_url - email_address - email_template - subscriber_filter 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: - broadcasts - pagination example: broadcasts: - id: 3 publication_id: 3 created_at: '2023-02-17T11:43:55Z' subject: Campaign subject 3 preview_text: null description: null public: false published_at: null send_at: null status: draft thumbnail_alt: null thumbnail_url: null content: null public_url: null email_address: greetings@kit.dev email_template: id: 6 name: Text Only subscriber_filter: - all: - type: all_subscribers - id: 2 publication_id: 2 created_at: '2023-02-17T11:43:55Z' subject: Campaign subject 2 preview_text: null description: null public: false published_at: null send_at: null status: draft thumbnail_alt: null thumbnail_url: null content: null public_url: null email_address: greetings@kit.dev email_template: id: 6 name: Text Only subscriber_filter: - all: - type: all_subscribers - id: 1 publication_id: 1 created_at: '2023-02-17T11:43:55Z' subject: Campaign subject 1 preview_text: null description: null public: false published_at: null send_at: null status: draft thumbnail_alt: null thumbnail_url: null content: null public_url: null email_address: greetings@kit.dev email_template: id: 6 name: Text Only subscriber_filter: - all: - type: all_subscribers pagination: has_previous_page: false has_next_page: false start_cursor: WzNd end_cursor: WzFd 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 x-mcp: enabled: true post: summary: Create a broadcast description: Draft or schedule to send a broadcast to all or a subset of your subscribers.

To save a draft, set `send_at` to `null`.

To publish to the web, set `public` to `true`.

To schedule the broadcast for sending, provide a `send_at` timestamp. Scheduled broadcasts should contain a subject and your content, at a minimum.

We currently support targeting your subscribers based on segment or tag ids. tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: [] responses: '201': description: Creates a new broadcast content: application/json: schema: type: object properties: broadcast: type: object properties: id: type: integer publication_id: type: integer created_at: type: string subject: type: string preview_text: type: string description: type: string content: type: string public: type: boolean published_at: type: string send_at: type: string nullable: true thumbnail_alt: type: string nullable: true thumbnail_url: type: string nullable: true public_url: type: string email_address: type: string email_template: type: object properties: id: type: integer name: type: string required: - id - name subscriber_filter: type: array items: type: object properties: all: type: array items: type: object properties: type: type: string enum: - segment - tag ids: type: array items: type: integer required: - type - ids required: - all status: type: string required: - id - publication_id - created_at - subject - preview_text - description - public - published_at - send_at - thumbnail_alt - thumbnail_url - content - public_url - email_address - email_template - subscriber_filter required: - broadcast example: broadcast: id: 64 publication_id: 55 created_at: '2023-02-17T11:43:55Z' subject: Hello! preview_text: Pleased to meet you! description: Intro email content:

Let me introduce myself

public: true published_at: '2023-02-17T11:43:55Z' send_at: null thumbnail_alt: null thumbnail_url: null public_url: https://kit-greetings.kit.com/posts/ email_address: greetings@kit.dev email_template: id: 2 name: Classic subscriber_filter: - all: - type: segment ids: - 18 status: draft '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 with an error message if the current account is unauthorized to create a broadcast content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - You do not have sufficient permissions to access this resource. Please contact support. '422': description: Returns a 422 with an error message when one or more of the parameters were invalid content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Email template not found - Only a single filter group is supported. Use one of `all`, `any`, or `none`. requestBody: content: application/json: schema: type: object properties: email_template_id: type: integer description: Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported. email_address: type: string nullable: true description: The sending email address to use. Uses the account's sending email address if not provided. content: type: string description: The HTML content of the email. description: type: string public: type: boolean description: '`true` to publish this broadcast to the web. The broadcast will appear in a newsletter feed on your Creator Profile and Landing Pages.' published_at: type: string description: The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed. send_at: type: string nullable: true description: The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed. thumbnail_alt: type: string nullable: true thumbnail_url: type: string nullable: true preview_text: type: string subject: type: string subscriber_filter: type: array description: Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. `all`, `any`, or `none` but no combinations). If nothing is provided, will default to all of your subscribers. items: type: object properties: all: type: array description: Filters your subscribers using a logical AND of all provided segment and tag ids, i.e. a subscriber would have to be part of all segments and tags provided items: type: object properties: type: type: string enum: - segment - tag description: '`segment` or `tag`' ids: type: array items: type: integer required: - type - ids any: type: array description: Filters your subscribers using a logical OR of all provided segment and tag ids, i.e. a subscriber would have to be part of at least one of the segments or tags provided items: type: object properties: type: type: string enum: - segment - tag description: '`segment` or `tag`' ids: type: array items: type: integer required: - type - ids nullable: true none: type: array description: Filters your subscribers using a logical NOT of all provided segment and tag ids, i.e. a subscriber would have to be in none of the segments or tags provided items: type: object properties: type: type: string enum: - segment - tag description: '`segment` or `tag`' ids: type: array items: type: integer required: - type - ids nullable: true minProperties: 1 required: - all - any - none required: - content - description - public - published_at - preview_text - subject - subscriber_filter example: email_template_id: 2 email_address: null content:

Let me introduce myself

description: Intro email public: true published_at: '2023-02-17T11:43:55+00:00' send_at: null thumbnail_alt: null thumbnail_url: null preview_text: Pleased to meet you! subject: Hello! subscriber_filter: - all: - type: segment ids: - 18 any: null none: null x-mcp: enabled: true /v4/broadcasts/stats: get: summary: Get stats for a list of broadcasts tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: - name: after in: query required: false schema: nullable: true description: To fetch next page of results, use `?after=` - name: before in: query required: false schema: nullable: true description: To fetch previous page of results, use `?before=` - name: include_total_count in: query required: false schema: type: boolean example: false 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. - name: per_page in: query required: false schema: nullable: true description: Number of results per page. Default 500, maximum 1000. - name: sent_after in: query required: false schema: nullable: true - name: sent_before in: query required: false schema: nullable: true responses: '200': description: Returns stats for all broadcasts on the account content: application/json: schema: type: object properties: broadcasts: type: array items: type: object properties: id: type: integer stats: type: object properties: recipients: type: integer open_rate: type: number format: float emails_opened: type: integer click_rate: type: number format: float unsubscribe_rate: type: number format: float unsubscribes: type: integer total_clicks: type: integer show_total_clicks: type: boolean status: type: string progress: type: number format: float open_tracking_disabled: type: boolean click_tracking_disabled: type: boolean required: - recipients - open_rate - emails_opened - click_rate - unsubscribe_rate - unsubscribes - total_clicks - show_total_clicks - status - progress - open_tracking_disabled - click_tracking_disabled subject: type: string send_at: nullable: true required: - id - stats 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: - broadcasts - pagination example: broadcasts: - id: 208 subject: '... or will you' send_at: null stats: recipients: 0 open_rate: 0.0 emails_opened: 0 click_rate: 0.0 unsubscribe_rate: 0.0 unsubscribes: 0 total_clicks: 0 show_total_clicks: false status: draft progress: 0.0 open_tracking_disabled: false click_tracking_disabled: false - id: 207 subject: You'll never guess... send_at: null stats: recipients: 0 open_rate: 0.0 emails_opened: 0 click_rate: 0.0 unsubscribe_rate: 0.0 unsubscribes: 0 total_clicks: 0 show_total_clicks: false status: draft progress: 0.0 open_tracking_disabled: false click_tracking_disabled: false pagination: has_previous_page: false has_next_page: false start_cursor: WzIwOF0= end_cursor: WzIwN10= 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 '403': description: Returns 403 if the account is not on a pro plan and has the feature flag disabled content: application/json: schema: type: object properties: {} required: - errors example: {} x-mcp: enabled: true /v4/broadcasts/{broadcast_id}/clicks: get: summary: Get link clicks for a broadcast description: 'NOTE: Pagination parameters control the list of clicks for the top level broadcast.' tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: - name: broadcast_id in: path required: true schema: type: integer example: 169 responses: '200': description: Returns clicks for a broadcast content: application/json: schema: type: object properties: broadcast: type: object properties: id: type: integer clicks: type: array items: type: object properties: url: type: string unique_clicks: type: integer click_to_delivery_rate: type: number format: float click_to_open_rate: type: number format: float required: - url - unique_clicks - click_to_delivery_rate - click_to_open_rate required: - id - clicks 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: - broadcast - pagination example: broadcast: id: 166 clicks: - url: https://example.com/52 unique_clicks: 3 click_to_delivery_rate: 0.006 click_to_open_rate: 0.03 - url: https://example.com/53 unique_clicks: 3 click_to_delivery_rate: 0.006 click_to_open_rate: 0.03 - url: https://example.com/54 unique_clicks: 3 click_to_delivery_rate: 0.006 click_to_open_rate: 0.03 pagination: has_previous_page: false has_next_page: false start_cursor: WzE4XQ== end_cursor: WzE4XQ== 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 /v4/broadcasts/{broadcast_id}/stats: get: summary: Get stats for a broadcast tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: - name: broadcast_id in: path required: true schema: type: integer example: 279 responses: '200': description: Returns stats for a broadcast content: application/json: schema: type: object properties: broadcast: type: object properties: id: type: integer stats: type: object properties: recipients: type: integer open_rate: type: number format: float emails_opened: type: integer click_rate: type: number format: float unsubscribe_rate: type: number format: float unsubscribes: type: integer total_clicks: type: integer show_total_clicks: type: boolean status: type: string progress: type: number format: float open_tracking_disabled: type: boolean click_tracking_disabled: type: boolean required: - recipients - open_rate - emails_opened - click_rate - unsubscribe_rate - unsubscribes - total_clicks - show_total_clicks - status - progress - open_tracking_disabled - click_tracking_disabled required: - id - stats required: - broadcast example: broadcast: id: 276 stats: recipients: 0 open_rate: 0.0 emails_opened: 0 click_rate: 0.0 unsubscribe_rate: 0.0 unsubscribes: 0 total_clicks: 0 show_total_clicks: false status: draft progress: 0.0 open_tracking_disabled: false click_tracking_disabled: false '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 /v4/broadcasts/{id}: delete: summary: Delete a broadcast tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: - name: id in: path required: true schema: type: integer example: 133 responses: '204': description: Deletes the broadcast '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 with an error message if the current account is unauthorized to update a broadcast content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - You do not have sufficient permissions to access this resource. Please contact support. '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 a 422 with an error message if the broadcast has already started sending or already sent content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Broadcast is already sending. x-mcp: enabled: true get: summary: Get a broadcast tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: - name: '[]' in: query required: false schema: type: string example: '' - name: id in: path required: true schema: type: integer example: 59 responses: '200': description: Returns the broadcast details content: application/json: schema: type: object properties: broadcast: type: object properties: id: type: integer publication_id: type: integer description: Identifier of the underlying publication. Broadcasts that are also published as posts share the same `publication_id` — use it to match a broadcast to its post via `GET /v4/posts`. created_at: type: string subject: type: string preview_text: type: string nullable: true description: type: string nullable: true content: type: string nullable: true public: type: boolean published_at: type: string nullable: true send_at: type: string nullable: true thumbnail_alt: type: string nullable: true thumbnail_url: type: string nullable: true public_url: type: string nullable: true email_address: type: string nullable: true email_template: type: object properties: id: type: integer name: type: string required: - id - name subscriber_filter: type: array items: type: object properties: all: type: array items: type: object properties: type: type: string required: - type required: - all status: type: string required: - id - publication_id - created_at - subject - preview_text - description - public - published_at - send_at - thumbnail_alt - thumbnail_url - content - public_url - email_address - email_template - subscriber_filter required: - broadcast example: broadcast: id: 57 publication_id: 48 created_at: '2023-02-17T11:43:55Z' subject: You'll never guess... preview_text: null description: null content: null public: false published_at: null send_at: null thumbnail_alt: null thumbnail_url: null public_url: null email_address: greetings@kit.dev email_template: id: 6 name: Text Only subscriber_filter: - all: - type: all_subscribers status: draft '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 broadcast description: Update an existing broadcast. Continue to draft or schedule to send a broadcast to all or a subset of your subscribers.

To save a draft, set `public` to false.

To schedule the broadcast for sending, set `public` to true and provide `send_at`. Scheduled broadcasts should contain a subject and your content, at a minimum.

We currently support targeting your subscribers based on segment or tag ids. tags: - Broadcasts security: - API Key: [] - OAuth2: [] parameters: - name: id in: path required: true schema: type: integer example: 106 responses: '200': description: Updates the broadcast and returns its details content: application/json: schema: type: object properties: broadcast: type: object properties: id: type: integer publication_id: type: integer created_at: type: string subject: type: string preview_text: type: string description: type: string content: type: string public: type: boolean published_at: type: string send_at: type: string thumbnail_alt: nullable: true thumbnail_url: nullable: true public_url: type: string email_address: type: string email_template: type: object properties: id: type: integer name: type: string required: - id - name subscriber_filter: type: array items: type: object properties: all: type: array items: type: object properties: type: type: string ids: type: array items: type: integer required: - type - ids required: - all status: type: string required: - id - publication_id - created_at - subject - preview_text - description - public - published_at - send_at - thumbnail_alt - thumbnail_url - content - public_url - email_address - email_template - subscriber_filter required: - broadcast example: broadcast: id: 92 publication_id: 83 created_at: '2023-02-17T11:43:55Z' subject: Hello! preview_text: Pleased to meet you! description: Intro email content:

Let me introduce myself

public: true published_at: '2023-02-17T11:43:55Z' send_at: '2023-02-17T11:43:55Z' thumbnail_alt: null thumbnail_url: null public_url: https://kit-greetings.kit.com/posts/hello email_address: greetings@kit.dev email_template: id: 2 name: Classic subscriber_filter: - all: - type: segment ids: - 54 status: sending '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 with an error message if the current account is unauthorized to create a broadcast content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - You do not have sufficient permissions to access this resource. Please contact support. '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 a 422 with an error message when one or more of the parameters are invalid or the campaign has already started sending content: application/json: schema: type: object properties: errors: type: array items: type: string required: - errors example: errors: - Email template not found - Only a single filter group is supported. Use one of `all`, `any`, or `none`. requestBody: content: application/json: schema: type: object properties: email_template_id: type: integer description: Id of the email template to use. Uses the account's default template if not provided. 'Starting point' template is not supported. email_address: type: string nullable: true description: The sending email address to use. Uses the account's sending email address if not provided. content: type: string description: The HTML content of the email. description: type: string public: type: boolean description: '`true` to publish this broadcast to the web. The broadcast will appear in a newsletter feed on your Creator Profile and Landing Pages.' published_at: type: string description: The published timestamp to display in ISO8601 format. If no timezone is provided, UTC is assumed. send_at: type: string description: The scheduled send time for this broadcast in ISO8601 format. If no timezone is provided, UTC is assumed. thumbnail_alt: nullable: true thumbnail_url: nullable: true preview_text: type: string subject: type: string subscriber_filter: type: array description: Filters your subscribers. At this time, we only support using only one filter group type via the API (e.g. `all`, `any`, or `none` but no combinations). If nothing is provided, will default to all of your subscribers. items: type: object properties: all: type: array description: Filters your subscribers using a logical AND of all provided segment and tag ids, i.e. a subscriber would have to be part of all segments and tags provided items: type: object properties: type: type: string description: '`segment` or `tag`' ids: type: array items: type: integer required: - type - ids any: type: array description: Filters your subscribers using a logical OR of all provided segment and tag ids, i.e. a subscriber would have to be part of at least one of the segments or tags provided items: type: object properties: type: type: string description: '`segment` or `tag`' ids: type: array items: type: integer required: - type - ids nullable: true none: type: array description: Filters your subscribers using a logical NOT of all provided segment and tag ids, i.e. a subscriber would have to be in none of the segments or tags provided items: type: object properties: type: type: string description: '`segment` or `tag`' ids: type: array items: type: integer required: - type - ids nullable: true minProperties: 1 required: - all - any - none required: - email_template_id - email_address - content - description - public - published_at - send_at - thumbnail_alt - thumbnail_url - preview_text - subject - subscriber_filter example: email_template_id: 2 email_address: null content:

Let me introduce myself

description: Intro email public: true published_at: '2023-02-17T11:43:55+00:00' send_at: '2023-02-17T11:43:55+00:00' thumbnail_alt: null thumbnail_url: null preview_text: Pleased to meet you! subject: Hello! subscriber_filter: - all: - type: segment ids: - 54 any: null none: null x-mcp: enabled: true components: 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