Broadcasts
Relevant source files
The following files were used as context for generating this wiki page:
Broadcasts represent bulk email campaigns sent to specific audiences within the Resend ecosystem. The system manages the creation, scheduling, execution, and tracking of these messages through a dedicated service layer.
The Broadcasts module allows you to send content to large groups of contacts, manage their delivery status, and track engagement metrics such as link clicks. It integrates with the Audience system to target specific recipient lists.
Sources: src/Service/Broadcast.php:40-48, tests/Fixtures/Broadcast.php:5-17
Architecture and Service Structure
The Broadcast functionality follows a service-resource pattern. The Resend\Service\Broadcast class acts as the primary interface for API interactions, while Resend\Broadcast represents the data object returned by the API.
Component Relationships
The Broadcast service contains a nested ClickedLink service to handle engagement tracking. The following diagram illustrates the relationship between these components:
The diagram shows how the Broadcast service manages the primary resource and provides access to engagement data through a sub-service.
Sources: src/Service/Broadcast.php:11-23, src/Broadcast.php:5-8
Lifecycle Management
Broadcasts progress through various states, typically starting as a draft. You can update, send, or cancel them depending on their current status.
Broadcast State Flow
The flowchart depicts the operational flow from initial creation to final execution or cancellation.
Sources: src/Service/Broadcast.php:83-145, tests/Service/Broadcast.php:97-124
Core Operations
| Operation | Method | Description |
|---|---|---|
| Create | create() | Initializes a new broadcast draft with audience and content. |
| Get | get() | Retrieves the details of a specific broadcast by ID. |
| Update | update() | Modifies an existing broadcast draft. |
| Send | send() | Triggers the delivery process or schedules it for later. |
| Cancel | cancel() | Halts a queued or scheduled broadcast. |
| Duplicate | duplicate() | Creates a new draft based on an existing broadcast. |
| Remove | remove() | Deletes a broadcast resource. |
Sources: src/Service/Broadcast.php:25-145, tests/Service/Broadcast.php:20-136
Recipient and Engagement Tracking
The system provides detailed visibility into who received a broadcast and how they interacted with it.
Recipient Filtering
You can retrieve recipients filtered by their interaction type. The recipients method accepts options to filter by events like sent, clicked, or bounced. When filtering by bounced, you can further specify the bounce_type (e.g., permanent).
Sources: src/Service/Broadcast.php:70-81, tests/Service/Broadcast.php:57-82
Engagement Data Model
Engagement is tracked through Recipient objects and ClickedLink objects.
| Field | Type | Description |
|---|---|---|
contact_id | string | The unique ID of the contact in the audience. |
email | string | The recipient's email address. |
clicked_links | array | List of URLs clicked by this recipient and click counts. |
bounce_type | string | Type of bounce reported (e.g., permanent). |
url | string | The specific URL tracked in the broadcast. |
unique_clicks | int | Number of unique contacts who clicked the link. |
Sources: tests/Fixtures/Broadcast.php:47-75, tests/Fixtures/Broadcasts/ClickedLink.php:5-20
Retrieval Flow
This sequence diagram shows the distinction between fetching individual recipient data and aggregate link click data.
Sources: src/Service/Broadcast.php:74-79, tests/Service/Broadcasts/ClickedLink.php:7-14
Implementation Example
To create and send a broadcast, you first define the payload and then invoke the send command.
// 1. Create the broadcast draft
$broadcast = $resend->broadcasts->create([
'audience_id' => '78261eea-8f8b-4381-83c6-79fa7120f1cf',
'from' => 'Acme <onboarding@resend.dev>',
'subject' => 'Weekly Newsletter',
'html' => '<strong>Hello world</strong>',
]);
// 2. Send the broadcast
$resend->broadcasts->send($broadcast->id, [
'scheduled_at' => '2024-12-25T12:00:00Z',
]);
Sources: src/Service/Broadcast.php:40-48, src/Service/Broadcast.php:97-105, tests/Service/Broadcast.php:24-32
Summary
Broadcasts provide a robust mechanism for managing bulk communication. By separating the drafting, sending, and tracking phases, the module ensures that developers can programmatically control the lifecycle of email campaigns while maintaining high visibility into recipient delivery and engagement performance.