Kit Developer Documentation

A broadcast is a one-time email blast that can either be sent right away or scheduled for a future time and date.

List broadcasts

Returns a list of the broadcasts for your account.

Endpoint

GET /v3/broadcasts

Parameters

api_secret

string

required

Your API secret key

page

integer

The page of results being requested. Default value is 1. Each page of results will contain up to 50 broadcasts.

sort_order

string

Sort order for results (asc or desc). The default is asc with the oldest first.

curl https://api.convertkit.com/v3/broadcasts?page=1&api_secret=<your_secret_api_key>

Create a broadcast

Create a draft or scheduled broadcast. You can create a draft broadcast without any attributes. Scheduled broadcasts at a minimum should contain a subject line and your content. Unless otherwise specified, new broadcasts will be sent from your account’s default email address and with your account’s default email template.

Endpoint

POST /v3/broadcasts

Parameters

api_secret

string

required

Your API secret key

content

string

The broadcast’s email content - this can contain text and simple HTML markdown (such as h1, img or p tags)

description

string

An internal description of this broadcast

email_address

string

Sending email address; leave blank to use your account’s default sending email address

email_layout_template

string

Name of the email template to use; leave blank to use your account’s default email template

public

string

Specifies whether or not this is a public post

published_at

string

Specifies the time that this post was published (applicable only to public posts)

send_at

string

Time that this broadcast should be sent; leave blank to create a draft broadcast. If set to a future time, this is the time that the broadcast will be scheduled to send.

subject

string

The broadcast email’s subject

thumbnail_alt

string

Specify the ALT attribute of the public thumbnail image (applicable only to public posts)

thumbnail_url

string

Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)

curl -X POST https://api.convertkit.com/v3/broadcasts\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "description": "Paid member newsletter for 04/26",
           "subject": "Weekly Update (04/26)",
           "content": "<p>Your content here</p>" }'

Retrieve a specific broadcast

Retrieve the details of a specific broadcast, including draft, scheduled, and previously-sent broadcasts.

Endpoint

GET /v3/broadcasts/#{broadcast_id}

Parameters

api_secret

string

required

Your API secret key

broadcast_id

integer

required

The ID of the broadcast you want to retrieve

curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>?api_secret=<your_secret_api_key>

Get stats

Get the statistics (recipient count, open rate, click rate, unsubscribe count, total clicks, status, and send progress) for a specific broadcast.

Endpoint

GET /v3/broadcasts/#{broadcast_id}/stats

Parameters

api_secret

string

required

Your API secret key

broadcast_id

integer

required

The ID of the broadcast you want to retrieve


curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>/stats?api_secret=<your_secret_api_key>

Update a broadcast

Update the attributes of a specific broadcast. Broadcasts that are currently sending or that have been sent may not be updated.

Endpoint

PUT /v3/broadcasts/#{broadcast_id}

Parameters

api_secret

string

required

Your API secret key

broadcast_id

integer

required

The ID of the broadcast you want to retrieve

content

string

The broadcast’s email HTML content

description

string

An internal description of this broadcast

email_address

string

Sending email address; leave blank to use your account’s default sending email address

email_layout_template

string

Name of the email template to use; leave blank to use your account’s default email template

public

string

Specifies whether or not this is a public post

published_at

string

Specifies the time that this post was published (applicable only to public posts)

send_at

string

Time that this broadcast should be sent; leave blank to create a “draft” broadcast. If set to a future time, this is the time that the broadcast will be scheduled to send.

subject

string

The broadcast’s email subject

thumbnail_alt

string

Specify the ALT attribute of the public thumbnail image (applicable only to public posts)

thumbnail_url

string

Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)

curl -X PUT https://api.convertkit.com/v3/broadcasts/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "content": "<h1>Welcome to our first newsletter!</h1><p>...</p>",
           "email_address": "[email protected]",
           "email_layout_template": "My Branded Template",
           "send_at": "2020-02-16T00:14:00.000Z" }'

Destroy a broadcast

Permanently delete a draft or scheduled broadcast record. Broadcasts that are currently sending or that have been sent may not be deleted.

Endpoint

DELETE /v3/broadcasts/#{broadcast_id}

Parameters

api_secret

string

required

Your API secret key

broadcast_id

string

required

The ID of the broadcast you want to retrieve

curl -X DELETE https://api.convertkit.com/v3/broadcasts/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>" }'

On this page

List broadcasts
Endpoint
Parameters
Create a broadcast
Endpoint
Parameters
Retrieve a specific broadcast
Endpoint
Parameters
Get stats
Endpoint
Parameters
Update a broadcast
Endpoint
Parameters
Destroy a broadcast
Endpoint
Parameters

A broadcast is a one-time email blast that can either be sent right away or scheduled for a future time and date.

List broadcasts

Returns a list of the broadcasts for your account.

Endpoint

GET /v3/broadcasts

Parameters

api_secret

string

required

Your API secret key

page

integer

The page of results being requested. Default value is 1. Each page of results will contain up to 50 broadcasts.

sort_order

string

Sort order for results (asc or desc). The default is asc with the oldest first.

curl https://api.convertkit.com/v3/broadcasts?page=1&api_secret=<your_secret_api_key>

Create a broadcast

Endpoint

POST /v3/broadcasts

Parameters

api_secret

string

required

Your API secret key

content

string

The broadcast’s email content - this can contain text and simple HTML markdown (such as h1, img or p tags)

description

string

An internal description of this broadcast

email_address

string

Sending email address; leave blank to use your account’s default sending email address

email_layout_template

string

Name of the email template to use; leave blank to use your account’s default email template

public

string

Specifies whether or not this is a public post

published_at

string

Specifies the time that this post was published (applicable only to public posts)

send_at

string

Time that this broadcast should be sent; leave blank to create a draft broadcast. If set to a future time, this is the time that the broadcast will be scheduled to send.

subject

string

The broadcast email’s subject

thumbnail_alt

string

Specify the ALT attribute of the public thumbnail image (applicable only to public posts)

thumbnail_url

string

Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)

curl -X POST https://api.convertkit.com/v3/broadcasts\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "description": "Paid member newsletter for 04/26",
           "subject": "Weekly Update (04/26)",
           "content": "<p>Your content here</p>" }'

Retrieve a specific broadcast

Retrieve the details of a specific broadcast, including draft, scheduled, and previously-sent broadcasts.

Endpoint

GET /v3/broadcasts/#{broadcast_id}

Parameters

api_secret

string

required

Your API secret key

broadcast_id

integer

required

The ID of the broadcast you want to retrieve

curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>?api_secret=<your_secret_api_key>

Get stats

Get the statistics (recipient count, open rate, click rate, unsubscribe count, total clicks, status, and send progress) for a specific broadcast.

Endpoint

GET /v3/broadcasts/#{broadcast_id}/stats

Parameters

api_secret

string

required

Your API secret key

broadcast_id

integer

required

The ID of the broadcast you want to retrieve


curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>/stats?api_secret=<your_secret_api_key>

Update a broadcast

Update the attributes of a specific broadcast. Broadcasts that are currently sending or that have been sent may not be updated.

Endpoint

PUT /v3/broadcasts/#{broadcast_id}

Parameters

api_secret

string

required

Your API secret key

broadcast_id

integer

required

The ID of the broadcast you want to retrieve

content

string

The broadcast’s email HTML content

description

string

An internal description of this broadcast

email_address

string

Sending email address; leave blank to use your account’s default sending email address

email_layout_template

string

Name of the email template to use; leave blank to use your account’s default email template

public

string

Specifies whether or not this is a public post

published_at

string

Specifies the time that this post was published (applicable only to public posts)

send_at

string

Time that this broadcast should be sent; leave blank to create a “draft” broadcast. If set to a future time, this is the time that the broadcast will be scheduled to send.

subject

string

The broadcast’s email subject

thumbnail_alt

string

Specify the ALT attribute of the public thumbnail image (applicable only to public posts)

thumbnail_url

string

Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)

curl -X PUT https://api.convertkit.com/v3/broadcasts/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "content": "<h1>Welcome to our first newsletter!</h1><p>...</p>",
           "email_address": "[email protected]",
           "email_layout_template": "My Branded Template",
           "send_at": "2020-02-16T00:14:00.000Z" }'

Destroy a broadcast

Permanently delete a draft or scheduled broadcast record. Broadcasts that are currently sending or that have been sent may not be deleted.

Endpoint

DELETE /v3/broadcasts/#{broadcast_id}

Parameters

api_secret

string

required

Your API secret key

broadcast_id

string

required

The ID of the broadcast you want to retrieve

curl -X DELETE https://api.convertkit.com/v3/broadcasts/1\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>" }'

On this page

List broadcasts
Endpoint
Parameters
Create a broadcast
Endpoint
Parameters
Retrieve a specific broadcast
Endpoint
Parameters
Get stats
Endpoint
Parameters
Update a broadcast
Endpoint
Parameters
Destroy a broadcast
Endpoint
Parameters

​List broadcasts

​Endpoint

​Parameters

​Create a broadcast

​Endpoint

​Parameters

​Retrieve a specific broadcast

​Endpoint

​Parameters

​Get stats

​Endpoint

​Parameters

​Update a broadcast

​Endpoint

​Parameters

​Destroy a broadcast

​Endpoint

​Parameters

Getting started

Guides

Endpoints

​List broadcasts

​Endpoint

​Parameters

​Create a broadcast

​Endpoint

​Parameters

​Retrieve a specific broadcast

​Endpoint

​Parameters

​Get stats

​Endpoint

​Parameters

​Update a broadcast

​Endpoint

​Parameters

​Destroy a broadcast

​Endpoint

​Parameters

List broadcasts

Endpoint

Parameters

Create a broadcast

Endpoint

Parameters

Retrieve a specific broadcast

Endpoint

Parameters

Get stats

Endpoint

Parameters

Update a broadcast

Endpoint

Parameters

Destroy a broadcast

Endpoint

Parameters

List broadcasts

Endpoint

Parameters

Create a broadcast

Endpoint

Parameters

Retrieve a specific broadcast

Endpoint

Parameters

Get stats

Endpoint

Parameters

Update a broadcast

Endpoint

Parameters

Destroy a broadcast

Endpoint

Parameters