Kit Developer Documentation

API V3 is deprecated and no longer in active development. Use API V4 for new projects, and see Upgrading to V4 to move an existing integration.

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

string

required

Your API secret key

integer

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

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

string

required

Your API secret key

string

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

string

An internal description of this broadcast

string

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

string

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

string

Specifies whether or not this is a public post

string

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

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.

string

The broadcast email’s subject

string

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

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

string

required

Your API secret key

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

string

required

Your API secret key

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

string

required

Your API secret key

integer

required

The ID of the broadcast you want to retrieve

string

The broadcast’s email HTML content

string

An internal description of this broadcast

string

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

string

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

string

Specifies whether or not this is a public post

string

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

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.

string

The broadcast’s email subject

string

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

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

string

required

Your API secret key

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.

Getting Started

Endpoints

Broadcasts

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