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>

{
  "broadcasts": [
    {
      "id": 1,
      "created_at": "2014-02-13T21:45:16.000Z",
      "subject": "Welcome to my Newsletter!"
    },
    {
      "id": 2,
      "created_at": "2014-02-20T11:40:11.000Z",
      "subject": "Check out my latest blog posts!"
    },
    {
      "id": 3,
      "created_at": "2014-02-29T08:21:18.000Z",
      "subject": "How to get my free masterclass"
    }
  ]
}

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

{
  "broadcast": {
    "id": 1,
    "created_at": "2020-02-14T00:00:00.000Z",
    "subject": "Weekly Update (04/26)",
    "description": "Paid member newsletter for 04/26",
    "content": "<p>Your content here</p>",
    "public": false,
    "published_at": null,
    "send_at": null,
    "thumbnail_alt": null,
    "thumbnail_url": null,
    "email_address": "default@example.com",
    "email_layout_template": "Text Only"
  }
}

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>

{
  "broadcast": {
    "id": 1,
    "created_at": "2020-02-14T00:00:00.000Z",
    "subject": "Weekly Update (04/26)",
    "description": "Paid member newsletter for 04/26",
    "content": "<p>Your content here</p>",
    "public": false,
    "published_at": null,
    "send_at": null,
    "thumbnail_alt": null,
    "thumbnail_url": null,
    "email_address": "default@example.com",
    "email_layout_template": "Text Only"
  }
}

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>

{
  "broadcast": [
    {
      "id":1,
      "stats":
      {
        "recipients": 82,
        "open_rate": 60.97560975609756,
        "click_rate": 23.170731707317074,
        "unsubscribes": 9,
        "total_clicks": 15,
        "show_total_clicks": false,
        "status": "completed",
        "progress": 100.0
      }
    }
  ]
}

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": "custom@example.com",
           "email_layout_template": "My Branded Template",
           "send_at": "2020-02-16T00:14:00.000Z" }'

{
  "broadcast": {
    "id": 1,
    "created_at": "2020-02-14T00:00:00.000Z",
    "subject": "Weekly Update (04/26)",
    "description": "Paid member newsletter for 04/26",
    "content": "<h1>Welcome to our first newsletter!</h1><p>...</p>",
    "public": false,
    "published_at": null,
    "send_at": "2020-02-16T00:14:00.000Z",
    "thumbnail_alt": null,
    "thumbnail_url": null,
    "email_address": "custom@example.com",
    "email_layout_template": "My Branded Template"
  }
}

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

No content will be returned.

​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