# SDKs & Client Libraries

> Official Broadcast client libraries for Ruby, PHP, Node/TypeScript, and Python: every API endpoint, with the same behaviour across every language.

Source: https://sendbroadcast.net/docs/sdks

Broadcast has a REST API, and you can call it with `curl`. The official client
libraries exist because a handful of details are easy to get wrong by hand (
retries that respect `Retry-After`, warnings on successful responses, credential
fields that come back masked) and getting them wrong is quiet rather than loud.

Every library covers **all 104 API operations**. None of them is a subset.

## Available Libraries

[Ruby Released on RubyGems. Includes an ActionMailer delivery method for Rails. gem 'broadcast-ruby'](https://sendbroadcast.net/docs/ruby-sdk) [PHP Released on Packagist. PHP 8.1+, one dependency, drops into Laravel or WordPress. composer require broadcast/broadcast-php](https://sendbroadcast.net/docs/php-sdk) [Node / TypeScript Released on npm. Node 18+, ESM and CommonJS, fully typed. npm install @send-broadcast/sdk](https://sendbroadcast.net/docs/node-sdk) [Python Released on PyPI. Python 3.9+, zero dependencies, fully type-hinted. pip install broadcast-python](https://sendbroadcast.net/docs/python-sdk)

| Language | Package | Status |
|---|---|---|
| **Ruby** | [`broadcast-ruby`](https://rubygems.org/gems/broadcast-ruby) | Released: [guide](/docs/ruby-sdk) · [source](https://github.com/send-broadcast/broadcast-ruby) |
| **PHP** | [`broadcast/broadcast-php`](https://packagist.org/packages/broadcast/broadcast-php) | Released: [guide](/docs/php-sdk) · [source](https://github.com/send-broadcast/broadcast-php) |
| **Node / TypeScript** | [`@send-broadcast/sdk`](https://www.npmjs.com/package/@send-broadcast/sdk) | Released: [guide](/docs/node-sdk) · [source](https://github.com/send-broadcast/broadcast-node) |
| **Python** | [`broadcast-python`](https://pypi.org/project/broadcast-python/) | Released: [guide](/docs/python-sdk) · [source](https://github.com/send-broadcast/broadcast-python) |

## What They All Do the Same Way

The libraries are not independent re-implementations. They share one behavioural
contract, so an integration you understand in Ruby reads the same in PHP.

**`host` is always required.** Broadcast is self-hosted first, so every instance
has its own domain. No client guesses one. All of them read `BROADCAST_HOST` and
`BROADCAST_API_TOKEN` from the environment, the same variables the
[Agents CLI](https://sendbroadcast.net/docs/agents-cli) stores in `~/.config/broadcast/config`.

**Warnings are surfaced, not swallowed.** A successful write can still report
that it ignored part of your request: a misspelled attribute, a filter it could
not parse. Every client exposes these on the response, and can be configured to
raise on them instead. See [API Response Warnings](https://sendbroadcast.net/docs/api-response-warnings).

**Retries are bounded and selective.** Timeouts, 429s, and 5xx are retried with
backoff, honouring `Retry-After` up to a configurable ceiling. A 422 is never
retried: it is deterministic, so retrying only adds latency.

**Credentials are protected from round-tripping.** The API returns credential
fields bullet-masked (`••••••••`). Reading an email server and writing it back
unchanged would replace a working SMTP password with those bullets. Every client
strips masked values out of update payloads and warns instead. This is a
data-loss guard, not a convenience.

**Redirects are never followed blindly.** Every request carries your API token.
A redirect to another host would hand that token over, so no client follows one,
and none follow redirects on writes at all. A redirect almost always means `host`
is misconfigured, and the error says so.

**Webhook verification is identical.** HMAC-SHA256 over `timestamp.payload`, a
five-minute tolerance, constant-time comparison. All four produce byte-identical
signatures for the same input.

## Choosing an Approach

| You want to | Use |
|---|---|
| Call the API from application code | An SDK |
| Send Rails mailer email through Broadcast | The Ruby SDK's ActionMailer delivery method |
| Script something from a terminal | The [Agents CLI](https://sendbroadcast.net/docs/agents-cli) |
| Give an AI agent access | [Agents](https://sendbroadcast.net/docs/agents) |
| Use a language with no SDK | The REST API directly, start at [API Authentication](https://sendbroadcast.net/docs/api-authentication) |
| Generate a client for a language with no SDK | Your installation's [OpenAPI spec](/docs/api-authentication#openapi-specification) |

## Getting an API Token

All the libraries authenticate the same way:

1. Log in to your Broadcast dashboard
2. Go to **Access Tokens** in the sidebar
3. Click **New Token**
4. Name it and select only the permissions your integration needs
5. Copy the token: it is shown once

If a token later turns out to need more access, you can change its permissions
without reissuing it: open the token and choose **Edit permissions**.
[API Authentication](https://sendbroadcast.net/docs/api-authentication) lists every permission and what it
covers.

Warning

Treat an API token like a password. It is not scoped to an IP address, and anyone holding it can act as your integration until you revoke it.

## Reporting Issues

Each library is open source and tracks issues in its own repository:

- [broadcast-ruby](https://github.com/send-broadcast/broadcast-ruby/issues)
- [broadcast-php](https://github.com/send-broadcast/broadcast-php/issues)
- [broadcast-node](https://github.com/send-broadcast/broadcast-node/issues)
- [broadcast-python](https://github.com/send-broadcast/broadcast-python/issues)

If the API itself is behaving unexpectedly rather than a client, the
[API Authentication](https://sendbroadcast.net/docs/api-authentication) section is the better starting point.