Audiences API (Deprecated)
Relevant source files
The following files were used as context for generating this wiki page:
The Audiences API manages groups of contacts within the Resend platform. As of version 3.0.0, this API is deprecated and maintained solely for backward compatibility. New implementations should use the Segments API.
The Audiences API acts as a wrapper around the newer Segments infrastructure. When you call Audience-related methods, the SDK routes requests to the /segments REST endpoints while returning data mapped to Audience structures.
Sources: examples/audiences.go:13-14, CHANGELOG.md:15-15, audiences_test.go:12-13
Architecture and Wrapper Logic
The Audiences API provides a legacy interface for contact organization. Internally, the Audiences service translates requests to the Segments service. For example, creating an audience triggers a POST request to the /segments endpoint rather than an /audiences endpoint.
Request Routing
The following diagram shows how the SDK handles legacy Audience calls by routing them to Segment endpoints.
API Operations
The API supports standard CRUD operations for managing audience groups.
Create Audience
You create an audience by providing a name. The API returns a unique identifier and confirming the object type as "segment".
| Parameter | Type | Description |
|---|---|---|
| Name | string | The display name of the audience/segment |
Sources: examples/audiences.go:21-25, audiences_test.go:41-43
Retrieve and List Audiences
You can retrieve a single audience by its ID or list all audiences associated with the project. Listing supports pagination through ListOptions.
| Method | Endpoint (Internal) | Description |
|---|---|---|
Get | GET /segments/{id} | Retrieves details for a specific audience |
List | GET /segments | Returns a list of all audience/segment objects |
Sources: examples/audiences.go:32-41, audiences_test.go:53-56, audiences_test.go:110-113
Remove Audience
Deleting an audience removes the group. This action is performed via a DELETE request to the segments endpoint.
Sources: examples/audiences.go:44-48, audiences_test.go:85-88
Integration with Contacts
Contacts can be associated with specific audiences. However, the AudienceId field in contact requests is now deprecated. The SDK handles these legacy contact requests by routing them through audience-specific sub-paths.
Sources: contacts.go:112-118, contacts.go:167-173
Contact Operations Table
| Operation | Legacy Path (with AudienceId) | Modern Path (Global) |
|---|---|---|
| Create | /audiences/{aud_id}/contacts | /contacts |
| Get | /audiences/{aud_id}/contacts/{id} | /contacts/{id} |
| List | /audiences/{aud_id}/contacts | /contacts |
| Remove | /audiences/{aud_id}/contacts/{id} | /contacts/{id} |
Sources: contacts.go:112-118, contacts.go:167-173, contacts.go:215-221, contacts.go:248-254
Data Structures
CreateAudienceRequest
type CreateAudienceRequest struct {
Name string `json:"name"`
}
Sources: audiences_test.go:41-43
Audience Response Object
The internal API returns a "segment" object which the SDK treats as an Audience.
| Field | Type | Description |
|---|---|---|
| Id | string | Unique identifier for the audience |
| Object | string | Always "segment" in the underlying API |
| Name | string | Name of the audience |
| CreatedAt | string | Timestamp of creation |
Sources: audiences_test.go:28-33, audiences_test.go:116-121
Summary
The Audiences API remains available to prevent breaking changes in existing codebases. It functions as a functional alias for the Segments API. Users are encouraged to migrate to client.Segments to access full functionality, as certain new features like global contact properties are only supported through the modern non-audience paths.
Sources: CHANGELOG.md:10-15, contacts.go:107-110