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>" }'