Segments API

Relevant source files

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

• segments.go
• contact_segments.go
• examples/segments.go
• examples/contact_segments.go
• segments_test.go
• CHANGELOG.md
• examples/with_pagination.go

The Segments API manages the organization of contacts into specific groups for targeted communication. In version 3.0.0, the Segments service replaced the Audiences service, which is now deprecated but maintained for backward compatibility.

This API provides two primary service interfaces: SegmentsSvc for managing the segment entities themselves, and ContactSegmentsSvc for managing the relationship between contacts and segments. Developers use these segments to target specific groups when creating or updating broadcasts.

Sources: CHANGELOG.md:16-25, segments.go:10-22

Service Architecture

The architecture consists of a primary Segments service and a specialized Contacts.Segments sub-service.

Core Service Components

The SegmentsSvc interface defines methods for CRUD operations on segment objects. The SegmentsSvcImpl implementation uses the Resend client to perform HTTP requests against the /segments endpoint.

This diagram shows the relationship between the primary Client and the two segment-related services.
Sources: segments.go:10-25, contact_segments.go:9-17

Data Models

The Segments API uses several structures to represent data and request parameters.

Segment Object

The Segment struct represents the core data entity.

Field	Type	Description
Id	string	Unique identifier for the segment
Name	string	The display name of the segment
Object	string	The object type, typically "segment"
CreatedAt	string	Timestamp of creation

Sources: segments.go:48-53

Request Structures

Methods use specific request types to ensure type safety and proper JSON serialization.

• CreateSegmentRequest: Contains the Name field for new segments.
• UpdateSegmentRequest: Contains the Name field for renaming existing segments.
• AddContactSegmentRequest: Requires SegmentId and either ContactId or Email.

Sources: segments.go:27-29, segments.go:35-37, contact_segments.go:23-27

Segment Management Operations

Managing segments involves creating, retrieving, updating, and deleting segment definitions.

Lifecycle Flow

The following flow demonstrates the standard lifecycle of a segment.

This flow represents the standard CRUD operations available for segment entities.
Sources: examples/segments.go:17-104

Creating and Updating

Creating a segment requires a name. The API returns a CreateSegmentResponse containing the new segment's ID. Updates are limited to changing the segment name via a PATCH request.

// Create a segment
params := &resend.CreateSegmentRequest{
    Name: "Premium Users",
}
segment, err := client.Segments.Create(params)
// Sources: [examples/segments.go:21-28]

Retrieval and Pagination

The ListWithOptions method supports cursor-based pagination using ListOptions.

Parameter	Type	Description
Limit	*int	Number of records to return (default 20)
After	*string	Cursor for fetching records after a specific ID
Before	*string	Cursor for fetching records before a specific ID

Sources: segments.go:81-82, examples/with_pagination.go:61-67

Contact Membership Management

The ContactSegmentsSvc handles the association between contacts and segments. This service is accessed via client.Contacts.Segments.

Membership Operations

Contacts can be added to or removed from segments using either their unique ContactId or their Email address.

This sequence shows how a contact is associated with a specific segment.
Sources: contact_segments.go:50-84

Membership Methods

1. Add: Associates a contact with a segment. Requires SegmentId.
2. Remove: Dissociates a contact from a segment. Returns a Deleted boolean status.
3. List: Retrieves all segments a specific contact belongs to.

Sources: contact_segments.go:9-17, examples/contact_segments.go:17-88

Integration with Broadcasts

Segments are primarily used as targets for broadcasts. The CreateBroadcastRequest and UpdateBroadcastRequest structures include a SegmentId field to specify the target audience.

Sources: CHANGELOG.md:22-23

Error Handling and Validation

The SDK performs basic validation before sending requests to the API.

• Update requires a non-empty segmentId.
• Update requires a non-empty Name in the params.
• Add membership requires SegmentId and at least one identifier (ContactId or Email).

Sources: segments.go:153-160, contact_segments.go:51-57, segments_test.go:189-195

Conclusion

The Segments API provides a structured way to group contacts and target them in broadcasts. By utilizing both the core Segments service and the Contacts.Segments sub-service, developers can manage complex subscriber groups and their memberships with full support for pagination and flexible identification.