Channel Settings API

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
• 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), 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.

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.

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

{
  "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

sender

unsubscribe_page

The URLs take no variables. A URL with {{ ... }} in it is refused.

confirmation_page

The confirmation page shows the same privacy_policy_url and legal_notice_url as the unsubscribe pages.

opt_in_forms

The three match_brand_kit switches are the switches on Settings → Brand Kit. The Brand Kit API does not change them.

Get Channel Settings

GET /api/v1/channel/settings

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.

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:

{
  "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:

{
  "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):

• 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).

{
  "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."
    }
  ]
}