Broadcasts

Relevant source files

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

• src/commands/broadcasts/index.ts
• src/commands/broadcasts/create.ts
• src/commands/broadcasts/send.ts
• src/commands/broadcasts/update.ts
• src/commands/broadcasts/utils.ts
• src/commands/broadcasts/list.ts
• skills/resend-cli/references/broadcasts.md

Broadcasts manage bulk email delivery to large groups of recipients organized by segments or topics. The system supports a draft-to-send lifecycle, allowing you to create, preview, update, and schedule bulk communications before final delivery.

Sources: src/commands/broadcasts/index.ts:20-22, skills/resend-cli/references/broadcasts.md

Lifecycle and Status

Broadcasts transition through several states during their existence. The CLI tracks these states to determine which actions are valid for a specific broadcast.

State Definitions

Status	Description
Draft	The initial state. You can update all properties and content.
Queued	The broadcast is currently being processed for delivery.
Scheduled	The broadcast waits for a specific future timestamp to begin delivery.
Sent	Delivery is complete. The broadcast content becomes immutable.

Sources: src/commands/broadcasts/utils.ts:4-15, src/commands/broadcasts/index.ts:22-28

Creating Broadcasts

The create command generates a new broadcast. You must provide a sender address, a subject, a target segment, and email content.

Body Content Options

You provide the email body using one of five mutually exclusive flags:

• --html: Inline HTML string.
• --html-file: Path to an HTML file (supports - for stdin).
• --text: Inline plain-text string.
• --text-file: Path to a text file (supports - for stdin).
• --react-email: Path to a .tsx template which the CLI bundles and renders.

Sources: src/commands/broadcasts/create.ts:24-42, skills/resend-cli/references/broadcasts.md:18-25

Variable Interpolation

Broadcasts support triple-brace interpolation for contact properties within HTML bodies.

• Syntax: {{{PROPERTY_NAME|fallback}}}
• Example: {{{FIRST_NAME|Friend}}} uses the contact's first name or defaults to "Friend".

Sources: src/commands/broadcasts/index.ts:31-32, src/commands/broadcasts/create.ts:107-111

Sending and Scheduling

You send a draft broadcast using the send command. This command only works for broadcasts created via the API or CLI; dashboard-created broadcasts require manual sending from the Resend dashboard.

Delivery Logic

1. Immediate Send: Execute resend broadcasts send <id> without timing flags.
2. Scheduled Send: Use the --scheduled-at flag with an ISO 8601 timestamp or natural language (e.g., "tomorrow at 9am ET").
3. Draft-to-Send: Use the --send flag during the create command to skip the draft state.

Management Operations

Listing and Retrieval

• List: broadcasts list returns summaries including ID, name, status, and creation date. It supports pagination via --after and --before.
• Get: broadcasts get <id> returns the full object, including the email body and sender details.

Sources: src/commands/broadcasts/list.ts:13-25, skills/resend-cli/references/broadcasts.md:41-43

Modification and Deletion

• Update: Modify a draft's from, subject, name, or content. Sent broadcasts are immutable and cannot be updated.
• Duplicate: Creates a new draft copy of any existing broadcast, including sent ones.
• Cancel: Reverts a scheduled broadcast to a draft or stops a queued broadcast mid-delivery.
• Delete: Removes the broadcast record. You must use the --yes flag in non-interactive environments.

Sources: src/commands/broadcasts/update.ts:10-14, skills/resend-cli/references/broadcasts.md:92-108, src/commands/broadcasts/index.ts:25-26

Analytics and Tracking

The CLI provides two primary commands for monitoring broadcast performance:

1. Recipients: Lists contacts associated with specific events (sent, delivered, opened, clicked, bounced, complained, unsubscribed, suppressed).
2. Clicked Links: Ranks links within the broadcast by total and unique click counts.

Feature	Parameters	Description
Recipient Filtering	--type, --email, --bounce-type	Filters the recipient list by event type or specific email substrings.
Link Analytics	--limit, --after, --before	Provides a ranked list of URLs and their performance metrics.

Sources: skills/resend-cli/references/broadcasts.md:45-66, src/commands/broadcasts/utils.ts:108-119

Broadcasts provide a robust mechanism for high-volume email distribution with integrated scheduling and analytics. By utilizing the draft-based workflow, you ensure content accuracy before initiating large-scale delivery via the Resend infrastructure.