SDKs and the CLI

You can call the Broadcast API with curl, and the earlier lessons did. For real code, an official library saves you from mistakes that are easy to make and hard to notice. In this lesson you choose between the SDKs and the CLI, and learn the behaviour they all share.

Four official libraries

There are official libraries for four languages, and each covers every API operation:

• Ruby: the broadcast-ruby gem. It includes an ActionMailer delivery method, so existing Rails mailers can send through Broadcast.
• PHP: broadcast/broadcast-php on Packagist, PHP 8.1 or later.
• Node and TypeScript: @send-broadcast/sdk on npm, Node 18 or later, fully typed.
• Python: broadcast-python on PyPI, Python 3.9 or later, with no dependencies.

For any other language, call the REST API directly, or generate a client from your installation’s OpenAPI spec at /api/v1/openapi.

A first call with the Node SDK

npm install @send-broadcast/sdk

import { Broadcast } from '@send-broadcast/sdk';

const client = new Broadcast({
  apiToken: process.env.BROADCAST_API_TOKEN,
  host: 'https://broadcast.example.com',
});

await client.subscribers.create({ email: 'ada@example.com', first_name: 'Ada' });

The other libraries follow the same shape. Each has a guide: Ruby, PHP, Node and Python.

What every library does the same way

The four libraries share one contract. Learn it once and it holds in every language.

host is always required. Broadcast is self-hosted, so every installation has its own domain. No client guesses one.

Warnings are surfaced. A successful write can still report that it ignored part of your request, such as a misspelled field. Every client exposes these warnings, and can be set to raise an error on them. In tests, turn that on.

Retries are bounded and selective. Timeouts, 429 and 5xx responses are retried with backoff, and Retry-After is honoured up to a ceiling. A 422 is never retried: the same request fails the same way.

Masked credentials are never written back. The API returns credential fields masked with bullets. If you read an email server and write it back unchanged, a naive client would replace your SMTP password with bullets. Every client strips masked values from updates and warns you instead.

Redirects are not followed. Every request carries your token. A redirect to another host would hand the token over, so the clients refuse. A redirect almost always means host is wrong.

Webhook verification is built in. Each library verifies webhook signatures with HMAC-SHA256, a five-minute tolerance and a constant-time comparison. The webhooks lesson explained why each step matters.

The broadcast CLI

The broadcast CLI is a single bash script that wraps the API. It needs only curl, and jq if you have it. Your own installation serves it. The exact install command is on the Agents page in your dashboard:

curl -fsSL https://broadcast.example.com/agents/install | bash
broadcast login --token=YOUR_API_TOKEN --host=https://broadcast.example.com
broadcast whoami

Use a channel token. The CLI does not send broadcast_channel_id, which admin tokens require. login saves the credentials to ~/.config/broadcast/config with owner-only permissions.

A few commands show the pattern:

broadcast status
broadcast subscribers find --email=ada@example.com
broadcast subscribers tag --email=ada@example.com --tag=vip
broadcast broadcasts create --subject="Weekly update" --body="<p>Hello</p>"
broadcast broadcasts stats 42

Output is JSON, which suits scripts. When jq is installed, the CLI pretty-prints it. Exit codes tell a script what went wrong: 1 authentication, 2 not found, 3 validation, 4 any other error, such as a rate limit or a server error.

broadcast prime prints everything your token can do: permissions, channel status, endpoints and rate limits. For anything without its own command, broadcast api METHOD PATH calls any endpoint.

After you upgrade Broadcast, run broadcast upgrade to get the matching CLI from your installation.

Which one to use

• Application code: an SDK.
• A Rails app that already sends mail with ActionMailer: the Ruby SDK’s delivery method.
• A one-off script, a cron job or a quick check from a terminal: the CLI.
• An AI agent: the next lesson.

Whichever you pick, give it its own token with only the permissions it needs. Treat that token like a password: anyone who holds it can act as your integration until you revoke it.

What you learned

• Official SDKs exist for Ruby, PHP, Node and Python, and each requires host.
• They all surface warnings, retry timeouts, 429 and 5xx (never 422), and protect masked credentials.
• The broadcast CLI comes from your own installation and uses a channel token.
• CLI output is JSON by default, with exit codes for scripts.