broadcast-api

aniketpanjwani's avatarfrom aniketpanjwani

Reference documentation for Broadcast API (sendbroadcast.net) integration. Use when working with the Broadcast email provider, creating/updating broadcasts, managing subscribers, or debugging API issues.

⭐32stars🔀2forks📁View on GitHub🕐Updated Dec 11, 2025
[API Helpers]

When & Why to Use This Skill

The Broadcast API skill is a comprehensive technical reference designed to streamline the integration of the sendbroadcast.net email marketing platform. It provides developers and agents with precise documentation for managing email broadcasts, handling subscriber lifecycles, and implementing secure Bearer token authentication. By offering detailed endpoint mappings and troubleshooting guides for common HTTP errors, this skill ensures reliable communication between your application—specifically the Payload Newsletter Plugin—and the Broadcast self-hosted service.

Use Cases

  • Automated Newsletter Management: Programmatically create, update, and schedule email broadcasts to maintain consistent communication with your audience.
  • Subscriber Synchronization: Efficiently manage subscriber lists by creating, finding, or updating user records and handling opt-in/opt-out status via API endpoints.
  • API Integration Debugging: Quickly identify and resolve technical issues such as 401 Unauthorized, 404 Not Found, or 422 Unprocessable Entity errors using structured common-issue references.
  • Custom Email Provider Setup: Facilitate the configuration of the Broadcast provider within development environments, ensuring correct base URL, token, and HTML body formatting.
namebroadcast-api
descriptionReference documentation for Broadcast API (sendbroadcast.net) integration. Use when working with the Broadcast email provider, creating/updating broadcasts, managing subscribers, or debugging API issues.
Provide accurate, up-to-date documentation for integrating with the Broadcast API in the Payload Newsletter Plugin. - Broadcast is a self-hosted email marketing platform at sendbroadcast.net - All API requests require Bearer token authentication - Base URL is your Broadcast instance domain (not sendbroadcast.net) - API responses use standard HTTP status codes

Authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

Base endpoints:

  • GET /api/v1/broadcasts - List broadcasts

  • POST /api/v1/broadcasts - Create broadcast

  • GET /api/v1/broadcasts/:id - Get broadcast

  • PATCH /api/v1/broadcasts/:id - Update broadcast

  • DELETE /api/v1/broadcasts/:id - Delete broadcast

  • POST /api/v1/broadcasts/:id/send_broadcast - Send broadcast

  • GET /api/v1/subscribers.json - List subscribers

  • GET /api/v1/subscribers/find.json?email= - Find subscriber

  • POST /api/v1/subscribers.json - Create subscriber

  • PATCH /api/v1/subscribers.json - Update subscriber

  • POST /api/v1/subscribers/unsubscribe.json - Unsubscribe

  • POST /api/v1/subscribers/resubscribe.json - Resubscribe

Broadcast statuses: draft | scheduled | queueing | sending | sent | failed | partial_failure | aborted | paused

| Topic | Reference File | |-------|----------------| | Broadcasts API (CRUD, sending, statistics) | references/broadcasts-api.md | | Subscribers API (CRUD, tags, filtering) | references/subscribers-api.md | | Authentication & tokens | references/authentication.md | | Overview & general info | references/overview.md |

Read the appropriate reference file based on what you're working on.

401 Unauthorized:

  • Token expired or revoked
  • Token lacks required permissions (Read vs Write)
  • Missing Bearer prefix in Authorization header

404 Not Found:

  • Broadcast/subscriber doesn't exist
  • Wrong base URL (using sendbroadcast.net instead of your instance)

422 Unprocessable Entity:

  • Missing required fields (subject, body for broadcasts)
  • Invalid email format for subscribers
  • Trying to update a sent broadcast

Body format for broadcasts:

  • Must be valid HTML
  • Use <br> for line breaks, <p> for paragraphs
  • Don't include <html>, <head>, <body> tags - Broadcast wraps content automatically
In this plugin, the Broadcast provider is at `src/providers/broadcast/broadcast.ts`

Key configuration:

{
  baseUrl: 'https://your-broadcast-instance.com',
  token: 'your_access_token',
  fromEmail: 'newsletter@yourdomain.com',
  fromName: 'Your Name',
  replyTo: 'reply@yourdomain.com'
}

The plugin creates broadcasts in Payload first, then syncs to Broadcast on first update with content (subject + body).

- API calls use correct endpoints and methods - Authentication header is properly formatted - Request bodies match expected schema - Error responses are handled appropriately