Broadcasts Management
Relevant source files
The following files were used as context for generating this wiki page:
Broadcasts Management provides the functionality to create, manage, and track large-scale email communications within the Resend ecosystem. The system allows users to target specific audiences or segments, schedule delivery, and analyze engagement metrics like recipient status and link clicks.
The Broadcasts module supports both synchronous and asynchronous execution, enabling integration into various Python application architectures. It facilitates the transition of broadcasts from initial drafts to sent or scheduled states, with options for duplication and removal of draft content.
Sources: resend/broadcasts/_broadcasts.py, examples/broadcasts.py
Core Data Structures
Broadcast Model
The Broadcast class defines the schema for broadcast objects returned by the API.
| Field | Type | Description |
|---|---|---|
id | str | Unique identifier for the broadcast. |
name | str | Friendly name for internal reference. |
subject | str | The email subject line. |
status | str | Current state (e.g., draft, sent, scheduled). |
segment_id | str | None | ID of the target segment. |
audience_id | str | None | ID of the target audience (Deprecated: use segment_id). |
from | str | Sender email address. |
html | str | None | HTML version of the message content. |
text | str | None | Plain text version of the message content. |
topic_id | str | None | ID of the topic scoping the broadcast. |
created_at | str | Timestamp of creation. |
sent_at | str | None | Timestamp when delivery occurred. |
Sources: resend/broadcasts/_broadcast.py:12-70, resend/broadcasts/_broadcasts.py:31-36
Recipient and Engagement Models
Recipients are tracked via specific event types and interaction counts. Link clicks are aggregated per URL to measure engagement.
Sources: resend/broadcasts/_broadcasts.py:270-360, tests/broadcasts_test.py:246-270
Lifecycle Management
Broadcasts follow a structured lifecycle from creation to delivery. You manage this lifecycle using the Broadcasts class methods.
Creation and Configuration
You create a broadcast by providing sender details, target identifiers, and content. If send is set to True in CreateParams, the system attempts immediate delivery or schedules it if scheduled_at is provided. Otherwise, the broadcast remains a draft.
The diagram shows the transition of a broadcast through different operational states.
Sources: resend/broadcasts/_broadcasts.py:463-500, tests/broadcasts_test.py:79-110
Operational Methods
| Method | HTTP Verb | Endpoint | Purpose |
|---|---|---|---|
create() | POST | /broadcasts | Initializes a new broadcast or draft. |
update() | PATCH | /broadcasts/{id} | Modifies an existing draft broadcast. |
send() | POST | /broadcasts/{id}/send | Triggers delivery for a specific draft. |
cancel() | POST | /broadcasts/{id}/cancel | Stops a queued or scheduled delivery. |
duplicate() | POST | /broadcasts/{id}/duplicate | Creates a new draft from an existing broadcast. |
remove() | DELETE | /broadcasts/{id} | Deletes a draft broadcast. |
Sources: resend/broadcasts/_broadcasts.py:463-652, tests/broadcasts_test.py:112-140
Recipient Tracking and Analytics
The system tracks every recipient interaction. You retrieve this data using the recipients and clicked_links methods.
Recipient Filtering
Recipient data can be filtered by event types such as sent, delivered, opened, clicked, or bounced. For bounced events, the system provides bounce_type (e.g., permanent). For opened and clicked events, a count is returned to indicate the number of interactions.
Sources: resend/broadcasts/_broadcasts.py:270-310, tests/broadcasts_test.py:246-300
Engagement Analysis
Engagement analysis focuses on unique and total clicks for URLs included in the broadcast content.
The sequence shows the process of fetching interaction metrics for specific links.
Sources: resend/broadcasts/_broadcasts.py:592-608, tests/broadcasts_test.py:339-360
Pagination Handling
List-based responses use cursor-based pagination. Methods like list(), recipients(), and clicked_links() accept ListParams including limit, after, and before.
limit: Defines the number of items per page (1 to 100).after: Retrieves items following the specified ID.before: Retrieves items preceding the specified ID.
Sources: resend/broadcasts/_broadcasts.py:228-268, resend/pagination_helper.py, examples/broadcasts.py:72-85
Asynchronous Support
Broadcast management supports asynchronous programming using await with _async method variants. These methods utilize the AsyncRequest handler to perform non-blocking HTTP operations.
Sources: resend/broadcasts/_broadcasts.py:654-790, examples/async/broadcasts_async.py:20-80, tests/broadcasts_async_test.py:15-100
Summary
Broadcasts Management enables developers to handle high-volume email distribution with fine-grained control over draft content, scheduling, and delivery cancellation. By providing detailed recipient event logs and click-through metrics, the system allows for comprehensive post-delivery analysis of audience engagement.