The Broadcasts API from Kit — 5 operation(s) for broadcasts.
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=<end_cursor>`
in: query
required: false
schema:
nullable: true
- name: before
description: To fetch previous page of results, use `?before=<start_cursor>`
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.<br/><br/>To save a draft, set `send_at` to `null`.<br/><br/>To publish to the web, set `public` to `true`.<br/><br/>To schedule the broadcast for sending, provide a `send_at` timestamp. Scheduled broadcasts should contain a subject and your content, at a minimum.<br/><br/>We currently support targeting your subscribers based on segment or tag ids.<aside class='notice'>Starting point templates are not currently supported.</aside>
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: <p>Let me introduce myself</p>
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: <p>Let me introduce myself</p>
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=<end_cursor>`
- name: before
in: query
required: false
schema:
nullable: true
description: To fetch previous page of results, use `?before=<start_cursor>`
- 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:
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convertkit/refs/heads/main/openapi/convertkit-broadcasts-api-openapi.yml