Broadcasts Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/broadcasts/broadcasts.ts
• src/broadcasts/broadcasts.spec.ts
• src/broadcasts/interfaces/create-broadcast-options.interface.ts
• src/broadcasts/interfaces/broadcast.ts
• src/broadcasts/interfaces/list-broadcast-recipients.interface.ts
• src/resend.ts

The Broadcasts Management module enables the creation, scheduling, and tracking of large-scale email campaigns sent to specific contact segments or audiences. It provides an interface for developers to manage the entire lifecycle of a broadcast, from initial draft creation to analyzing recipient engagement metrics such as opens and link clicks.

Broadcasts are managed through the Broadcasts class, which is instantiated as a member of the main Resend client. This module integrates with the Segments and Topics features to target recipients and allows for either immediate delivery or scheduled execution using ISO 8601 timestamps.
Sources: src/broadcasts/broadcasts.ts:46-48, src/resend.ts:60, src/broadcasts/interfaces/create-broadcast-options.interface.ts:48-56

Architecture and Core Logic

The Broadcasts class interacts with the Resend API via standard HTTP methods (POST, GET, PATCH, DELETE). It handles the transformation of developer-friendly options into the snake_case format required by the API backend.

The diagram above shows the relationship between the main library entry point and the specific broadcast operations.
Sources: src/broadcasts/broadcasts.ts:46-177, src/resend.ts:168-250

Broadcast Data Structure

A Broadcast object contains the configuration for the email content and the targeting metadata.

Field	Type	Description
id	string	Unique identifier for the broadcast.
status	'draft' | 'sent' | 'queued'	Current state of the broadcast.
segment_id	string | null	The ID of the targeted recipient segment.
from	string	Sender email address or "Name <email>" format.
subject	string	The email subject line.
scheduled_at	string | null	ISO 8601 timestamp for planned delivery.
Sources: src/broadcasts/interfaces/broadcast.ts:1-16

Broadcast Lifecycle Management

Creation and Content Rendering

You create a broadcast by providing sender details, targeting info (segment or audience), and content. The module supports three content formats: raw HTML, plain text, or React components. If a React component is provided via the react property, the module renders it into HTML before transmission.

This flow illustrates how React components are transformed before reaching the API.
Sources: src/broadcasts/broadcasts.ts:50-78, src/broadcasts/interfaces/create-broadcast-options.interface.ts:5-46

Scheduling and Delivery

Delivery is controlled by the send boolean during creation or by the explicit send() method for existing drafts.

1. Immediate Send: Set send: true during creation.
2. Scheduled Send: Set send: true and provide a scheduledAt timestamp.
3. Draft to Send: Create with send: false, then call broadcasts.send(id).
   Sources: src/broadcasts/broadcasts.ts:80-92, src/broadcasts/interfaces/create-broadcast-options.interface.ts:48-80

Maintenance Operations

The module provides several methods to manage existing broadcasts:

• Get: Retrieves full details of a specific broadcast by ID.
• Update: Modifies the fields of a draft broadcast. It re-renders content if a new React component is provided.
• Duplicate: Creates a new draft broadcast based on an existing one.
• Cancel: Stops a broadcast that is currently in 'queued' or 'scheduled' status.
• Remove: Permanently deletes a broadcast record.
  Sources: src/broadcasts/broadcasts.ts:104-107, src/broadcasts/broadcasts.ts:152-177, src/broadcasts/broadcasts.spec.ts:809-813

Tracking and Analytics

The system tracks individual recipient events and aggregate link performance.

Recipient Engagement

The recipients method allows filtering the recipient list by event type. Supported types include sent, delivered, opened, clicked, bounced, complained, unsubscribed, and suppressed.

For the clicked type, the API returns additional metadata including a list of clicked_links and the click count per link. For bounced, it includes the bounce_type (permanent, transient, or undetermined).
Sources: src/broadcasts/broadcasts.ts:114-124, src/broadcasts/interfaces/list-broadcast-recipients.interface.ts:8-44

Clicked Links Analysis

The clickedLinks method provides a summary of URL performance within the broadcast. It returns the total number of clicks and unique clicks for every link included in the email body.
Sources: src/broadcasts/broadcasts.ts:133-143, src/broadcasts/broadcasts.spec.ts:575-585

API Request Parameters

List Broadcasts Options

When listing broadcasts, the following pagination parameters are available:

Parameter	Type	Description
limit	number	Number of records to return (defaults to API standard).
after	string	Cursor for forward pagination.
before	string	Cursor for backward pagination.
Sources: src/broadcasts/broadcasts.ts:94-102, src/broadcasts/broadcasts.spec.ts:316-340

Recipient Query Filters

The recipients method uses a specific query builder to handle event-specific filtering.

function buildRecipientsQuery(options: ListBroadcastRecipientsOptions) {
  const { type, email, bounceType, ...pagination } = options;
  const searchParams = new URLSearchParams(buildPaginationQuery(pagination));
  searchParams.set('type', type);
  if (email !== undefined) searchParams.set('email', email);
  if (bounceType !== undefined) searchParams.set('bounce_type', bounceType);
  return searchParams.toString();
}

Sources: src/broadcasts/broadcasts.ts:179-193

Summary

Broadcasts Management provides a robust programmatic interface for orchestrating email campaigns. It leverages the core Resend fetch architecture to ensure consistent header handling, such as Authorization and User-Agent, while adding specific logic for template rendering and recipient event filtering. This module is essential for workflows requiring targeted bulk communication and detailed engagement reporting.
Sources: src/broadcasts/broadcasts.ts:46-48, src/resend.ts:91-105