Broadcasts API

Relevant source files

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

• broadcasts.go
• examples/broadcasts.go
• broadcasts_test.go
• errors.go
• CHANGELOG.md
• examples/with_pagination.go

The Broadcasts API allows you to manage and send bulk email communications to specific groups of contacts. You use this API to create drafts, schedule delivery, duplicate existing broadcasts, and track recipient engagement through events like opens and clicks.

Broadcasts target Segments of your audience. While the API previously used AudienceId, that field is now deprecated in favor of SegmentId to align with the project's shift toward segment-based organization.
Sources: broadcasts.go:27-28, CHANGELOG.md:16-17

Broadcast Lifecycle Management

The BroadcastsSvc interface defines the core operations for managing a broadcast's lifecycle. A broadcast typically begins as a draft and progresses to a sent or scheduled state.

Lifecycle Flow

The following diagram illustrates the typical progression of a broadcast from creation to final delivery or deletion.

Core Operations

Operation	Description	Requirements
Create	Creates a new broadcast entity.	Requires SegmentId, From, and Subject.
Update	Modifies an existing draft broadcast.	Requires BroadcastId.
Send	Triggers immediate or scheduled delivery of a draft.	Requires BroadcastId.
Cancel	Cancels a scheduled broadcast before it is sent.	Requires BroadcastId.
Duplicate	Creates a new draft copy of an existing broadcast.	Appends " (copy)" to the name.
Remove	Permanently deletes a broadcast.	Only permitted for drafts.

Sources: broadcasts.go:214-368, examples/broadcasts.go:108-110

Data Structures

CreateBroadcastRequest

This structure contains the parameters required to initialize a broadcast.

Field	Type	Description
SegmentId	string	The ID of the segment to target.
From	string	The sender email address.
Subject	string	The email subject line.
Html	string	The HTML content of the email.
Text	string	The plain text content of the email.
Send	bool	If true, sends the broadcast immediately.
ScheduledAt	string	ISO 8601 or natural language date for delayed sending.

Sources: broadcasts.go:26-44

Broadcast Object

The Broadcast struct represents the retrieved state of a broadcast entity.

type Broadcast struct {
	Object      string   `json:"object"`
	Id          string   `json:"id"`
	Name        string   `json:"name"`
	SegmentId   string   `json:"segment_id"`
	Status      string   `json:"status"`
	CreatedAt   string   `json:"created_at"`
	ScheduledAt string   `json:"scheduled_at"`
	SentAt      string   `json:"sent_at"`
}

Sources: broadcasts.go:189-205

Recipient Tracking and Analytics

The API provides methods to retrieve detailed engagement data for each broadcast. You can filter recipients by event type and view specific interactions like clicked links.

Recipient Event Types

You must specify a Type when listing recipients. Valid types include:

• sent: Successfully sent to the provider.
• delivered: Accepted by the recipient's mail server.
• opened: The recipient opened the email.
• clicked: The recipient clicked a link within the email.
• bounced: The email failed delivery.
• complained: The recipient marked the email as spam.
• unsubscribed: The recipient opted out via this broadcast.
  Sources: broadcasts.go:94-104

Tracking Logic Flow

Clicked Links

The ClickedLinks method returns an aggregated list of URLs within the broadcast and their performance metrics.

• URL: The actual link address.
• Clicks: Total number of times the link was clicked.
• UniqueClicks: Number of unique recipients who clicked the link.
  Sources: broadcasts.go:179-187, broadcasts_test.go:535-555

Error Handling

The SDK defines specific sentinel errors for the Broadcasts service to assist in debugging request preparation failures.

Error Constant	Description
ErrFailedToCreateBroadcastCreateRequest	Occurs when the SDK fails to build the POST request for creation.
ErrFailedToCreateBroadcastSendRequest	Occurs when the SDK fails to build the POST request for sending.
ErrFailedToCreateBroadcastRecipientsRequest	Occurs when parameters for the recipients list are invalid.

Validation also occurs within the service implementation. For example, CreateWithContext returns an error if From, Subject, or a targeting ID (SegmentId/AudienceId) is missing.
Sources: errors.go:61-68, broadcasts.go:232-243

Summary

The Broadcasts API provides a robust framework for managing high-volume email campaigns through segments. By leveraging the lifecycle methods, you can programmatically control the draft, scheduling, and delivery phases while gaining granular insights into recipient behavior through event-based tracking and click analytics.