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