> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Broadcasts

> Broadcasts v3 endpoints

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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="page" type="integer">
  The page of results being requested. Default value is `1`. Each page of results will contain up to 50 broadcasts.
</ParamField>

<ParamField path="sort_order" type="string">
  Sort order for results (`asc` or `desc`). The default is `asc` with the oldest first.
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/broadcasts?page=1&api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="content" type="string">
  The broadcast's email content - this can contain text and simple HTML markdown (such as `h1`, `img` or `p` tags)
</ParamField>

<ParamField path="description" type="string">
  An internal description of this broadcast
</ParamField>

<ParamField path="email_address" type="string">
  Sending email address; leave blank to use your account's default sending email address
</ParamField>

<ParamField path="email_layout_template" type="string">
  Name of the email template to use; leave blank to use your account's default email template
</ParamField>

<ParamField path="public" type="string">
  Specifies whether or not this is a public post
</ParamField>

<ParamField path="published_at" type="string">
  Specifies the time that this post was published (applicable only to public posts)
</ParamField>

<ParamField path="send_at" type="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.
</ParamField>

<ParamField path="subject" type="string">
  The broadcast email's subject
</ParamField>

<ParamField path="thumbnail_alt" type="string">
  Specify the ALT attribute of the public thumbnail image (applicable only to public posts)
</ParamField>

<ParamField path="thumbnail_url" type="string">
  Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  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>" }'
  ```

  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="broadcast_id" type="integer" required={true}>
  The ID of the broadcast you want to retrieve
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>?api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="broadcast_id" type="integer" required={true}>
  The ID of the broadcast you want to retrieve
</ParamField>

<CodeGroup>
  ```shell Request theme={null}

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

  ```json Response theme={null}
  {
    "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
        }
      }
    ]
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="broadcast_id" type="integer" required={true}>
  The ID of the broadcast you want to retrieve
</ParamField>

<ParamField path="content" type="string">
  The broadcast's email HTML content
</ParamField>

<ParamField path="description" type="string">
  An internal description of this broadcast
</ParamField>

<ParamField path="email_address" type="string">
  Sending email address; leave blank to use your account's default sending email address
</ParamField>

<ParamField path="email_layout_template" type="string">
  Name of the email template to use; leave blank to use your account's default email template
</ParamField>

<ParamField path="public" type="string">
  Specifies whether or not this is a public post
</ParamField>

<ParamField path="published_at" type="string">
  Specifies the time that this post was published (applicable only to public posts)
</ParamField>

<ParamField path="send_at" type="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.
</ParamField>

<ParamField path="subject" type="string">
  The broadcast's email subject
</ParamField>

<ParamField path="thumbnail_alt" type="string">
  Specify the ALT attribute of the public thumbnail image (applicable only to public posts)
</ParamField>

<ParamField path="thumbnail_url" type="string">
  Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  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" }'
  ```

  ```json Response theme={null}
  {
    "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"
    }
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="broadcast_id" type="string" required={true}>
  The ID of the broadcast you want to retrieve
</ParamField>

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

  ```json Response theme={null}
  No content will be returned.
  ```
</CodeGroup>