# Channel Settings API

> Read and change a channel's settings through the Broadcast API, including the channel language, sender details, the unsubscribe page, the legal links and the confirmation page.

Source: https://sendbroadcast.net/docs/api-channel-settings

Note

**Requires Broadcast 2.46.0 or later.**

The Channel Settings API reads and changes the settings of the token's channel. They are the settings you set under **Settings** in Broadcast, grouped the same way:

- `general`: Settings → General Channel Settings
- `sender`: Settings → Sender Details
- `unsubscribe_page`: Settings → Unsubscribe Page, including the legal links
- `confirmation_page`: the channel settings of the double opt-in [Confirmation Pages](https://sendbroadcast.net/docs/confirmation-pages)
- `opt_in_forms`: whether new opt-in forms start from the brand kit (the third switch on Settings → Brand Kit)

The API never reads or writes secrets, provider webhook keys, the channel domain, email servers, sender identities, users or billing. The brand kit has its own endpoint, `/api/v1/channel/design` (see the [Brand Kit API](https://sendbroadcast.net/docs/api-channel-design)), which needs the same Channel Settings write permission to change it. The confirmation page **text** belongs to a confirmation template, so it is in the [Templates API](https://sendbroadcast.net/docs/api-templates).

## Required Permissions

- **Channel Settings read**: get the settings
- **Channel Settings write**: change the settings

Both are off on every token until you tick them, including tokens created before 2.46.0. Set them under **Access Tokens** (and **Admin API Tokens**). See [API Authentication](https://sendbroadcast.net/docs/api-authentication).

An admin API token must name the channel with `broadcast_channel_id`, as a query parameter for `GET` and in the body for `PATCH`.

## Channel Settings Object

```json
{
  "general": {
    "name": "Northwind News",
    "language": "de",
    "hard_bounces_block_transactional": false
  },
  "sender": {
    "sender_name": "Northwind",
    "sender_email": "news@northwind.example",
    "physical_address": "Hauptstraße 1, 10115 Berlin",
    "email_footer": "<a href=\"{{ unsubscribe_url }}\">Von unseren E-Mails abmelden</a>",
    "use_email_footer": true
  },
  "unsubscribe_page": {
    "require_confirmation": true,
    "topic_unsubscribe_scope": "topic",
    "match_browser_language": false,
    "languages": ["en"],
    "privacy_policy_url": "https://northwind.example/datenschutz",
    "legal_notice_url": "https://northwind.example/impressum",
    "redirect_url": null,
    "match_brand_kit": true,
    "appearance": {
      "colors": { "accent": "#16a34a" },
      "unsubscribe_button": "red",
      "show_logo": true,
      "show_social_links": true
    },
    "text": {
      "en": { "confirm": { "heading": "Leaving us?" } }
    }
  },
  "confirmation_page": {
    "link_expiration_hours": 24,
    "match_brand_kit": true,
    "appearance": {
      "colors": {},
      "show_logo": true,
      "show_social_links": true
    }
  },
  "opt_in_forms": {
    "match_brand_kit": false
  }
}
```

### general

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | The channel name. Required, and unique on the server. |
| `language` | string | The channel language: `en`, `de`, `fr`, `es`, `it`, `pt`, `nl`, `pl`, `sv`, `da`, `nb`, `fi` or `ja`. Every public page uses it, and so does the default email footer. |
| `hard_bounces_block_transactional` | boolean | Whether a hard bounce also stops transactional emails to that address. |

### sender

| Field | Type | Description |
|-------|------|-------------|
| `sender_name` | string | The default sender name. |
| `sender_email` | string | The default sender address. Changing it updates the channel's default sender identity, which you must verify again before it sends. |
| `physical_address` | string | The postal address for the email footer. |
| `email_footer` | string | The footer HTML added to emails. |
| `use_email_footer` | boolean | Whether the footer is added. |

### unsubscribe_page

| Field | Type | Description |
|-------|------|-------------|
| `require_confirmation` | boolean | Subscribers click a button to unsubscribe, which stops email security scanners unsubscribing people. |
| `topic_unsubscribe_scope` | string | On an email sent to a topic: `topic` (turn off only that topic) or `everything`. |
| `match_browser_language` | boolean | Show public pages in the browser's language when it is one of the channel's languages. |
| `languages` | array | The languages public pages offer besides `general.language`. Sending it replaces the list. |
| `privacy_policy_url` | string or null | Your privacy policy. An absolute `http://` or `https://` URL. Shown at the bottom of every unsubscribe page and every confirmation page. |
| `legal_notice_url` | string or null | Your legal notice (Impressum). The same rules as `privacy_policy_url`. |
| `redirect_url` | string or null | An `https://` URL to send subscribers to after they unsubscribe. |
| `match_brand_kit` | boolean | Use the brand kit's logo, colours, font, corner radius and social links. |
| `appearance.colors` | object | Hex colours (`#rrggbb`) for `page_background`, `card_background`, `text`, `muted`, `link` and `accent`. A colour that is not set follows the brand kit. |
| `appearance.unsubscribe_button` | string | `red` or `accent`. |
| `appearance.show_logo`, `appearance.show_social_links` | boolean | Whether the brand kit's logo and social links show. |
| `text` | object | Your own page text: `{ "": { "": { "": "..." } } }`. The pages and fields are the ones under Settings → Unsubscribe Page (for example `confirm` with `heading`, `message`, `confirm_button` and `stay_button`). A field that is not set uses the built-in text. See [Unsubscribe Settings](https://sendbroadcast.net/docs/unsubscribe-settings). | The URLs take no variables. A URL with `{{ ... }}` in it is refused. ### confirmation_page | Field | Type | Description | |-------|------|-------------| | `link_expiration_hours` | integer | How long a confirmation link stays usable: `24`, `48`, `168` (7 days), `720` (30 days) or `0` (never). | | `match_brand_kit` | boolean | Use the brand kit on the confirmation page. | | `appearance.colors` | object | The same colours as the unsubscribe page. | | `appearance.show_logo`, `appearance.show_social_links` | boolean | Whether the brand kit's logo and social links show. | The confirmation page shows the same `privacy_policy_url` and `legal_notice_url` as the unsubscribe pages. ### opt_in_forms | Field | Type | Description | |-------|------|-------------| | `match_brand_kit` | boolean | New opt-in forms start from the brand kit's accent, text colours, font and corner radius, and the form designer offers **Apply brand kit**. Existing forms do not change. | The three `match_brand_kit` switches are the switches on Settings → Brand Kit. The [Brand Kit API](https://sendbroadcast.net/docs/api-channel-design) does not change them. ## Get Channel Settings `GET /api/v1/channel/settings`
```bash
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://your-broadcast-domain.com/api/v1/channel/settings
```

 Returns `200` with the channel settings object. Settings you never changed show their defaults. ## Update Channel Settings `PATCH /api/v1/channel/settings` Send the settings to change inside `channel_settings`. Only what you send changes: - A setting you leave out stays as it is. - In `text` and `appearance.colors`, the values you send merge with the stored ones. Send `""` or `null` to remove one, so it goes back to the built-in text or the brand kit. - `languages` replaces the whole list. - Send `null` (or `""`) for `privacy_policy_url`, `legal_notice_url` or `redirect_url` to remove the link.
```bash
curl -X PATCH \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "channel_settings": {
      "unsubscribe_page": {
        "privacy_policy_url": "https://northwind.example/datenschutz",
        "legal_notice_url": "https://northwind.example/impressum"
      }
    }
  }' \
  https://your-broadcast-domain.com/api/v1/channel/settings
```

 Returns `200` with the whole channel settings object after the change, so you can check what was saved. ### Errors A `422` saves nothing. There are two kinds. A value that is not one of the allowed values: `general.language`, `unsubscribe_page.topic_unsubscribe_scope`, `unsubscribe_page.appearance.unsubscribe_button`, `confirmation_page.link_expiration_hours`, or a language in `unsubscribe_page.languages`. A switch (any boolean field) that is not `true` or `false` is refused the same way, with the message `must be true or false`. The strings `"true"`, `"false"`, `"1"` and `"0"` are also accepted:
```json
{
  "error": "Unprocessable Content",
  "message": "channel_settings.general.language must be one of en, de, fr, es, it, pt, nl, pl, sv, da, nb, fi, ja"
}
```

 A setting that fails validation, for example a blank `general.name`, a legal link that is not an `http://` or `https://` URL, a `redirect_url` that is not `https://`, or a colour that is not a hex colour:
```json
{
  "error": "Unsubscribe page settings legal notice link must be an http(s) URL"
}
```

 A body without a `channel_settings` object returns `400`. A token without the permission returns `401`. ### Warnings The response can carry a `warnings` array (see [API Response Warnings](https://sendbroadcast.net/docs/api-response-warnings)): - `unrecognized_parameter`: a key that is not a setting, at any depth, for example `channel_settings.general.domain` or `channel_settings.unsubscribe_page.appearance.colors.glow`. The key is ignored and the rest is saved. - `parameter_overridden`: Broadcast changed a value you sent. This happens when `unsubscribe_page.languages` includes the channel language (every page speaks it, so it is left out of the list), and when you change `general.language` and send the old language's default `sender.email_footer` (the footer becomes the new language's default).
```json
{
  "general": { "...": "..." },
  "warnings": [
    {
      "code": "unrecognized_parameter",
      "param": "channel_settings.general.domain",
      "message": "domain is not a recognized key in channel_settings.general and was ignored. Recognized keys: name, language, hard_bounces_block_transactional."
    }
  ]
}
```