Audiences Management

Relevant source files

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

• resend/audiences/_audiences.py
• resend/audiences/_audience.py
• examples/audiences.py
• tests/audiences_test.py
• tests/audiences_async_test.py
• examples/contacts.py

Audiences Management allows you to group contacts for organized email delivery and marketing campaigns. The Audiences module provides methods to create, retrieve, list, and delete audience groups within the Resend ecosystem.

In the current version of the Resend Python SDK, the Audiences class is technically deprecated and acts as an alias for Segments. All calls to Audiences methods trigger a DeprecationWarning and redirect execution to the Segments implementation.
Sources: resend/audiences/_audiences.py:100-111, resend/audiences/_audiences.py:129-140

Architecture and Data Flow

The Audiences module interfaces with the Resend API to persist and manage audience data. It utilizes synchronous and asynchronous request handlers to perform CRUD operations.

The diagram shows how the Audiences module serves as a wrapper that delegates calls to the Segments implementation before reaching the Resend API.
Sources: resend/audiences/_audiences.py:100-244

Key Components

Data Structures

The module defines specific TypedDict structures for request parameters and response objects to ensure type safety.

Structure	Type	Description
CreateParams	TypedDict	Contains the name required to create a new audience.
ListParams	TypedDict	Optional pagination parameters: limit, after, and before.
Audience	TypedDict	The core data model representing a single audience group.
ListResponse	BaseResponse	Wraps a list of Audience objects and pagination metadata.
Sources: resend/audiences/_audiences.py:46-97

Core Methods

The Audiences class provides the following static methods for management:

• create(params): Generates a new audience group with a specified name.
• get(id): Retrieves detailed information for a specific audience.
• list(params): Fetches a collection of audiences, supporting pagination via limit and cursors.
• remove(id): Deletes an existing audience.

Each method has a corresponding _async version (e.g., create_async) for use in asynchronous environments.
Sources: resend/audiences/_audiences.py:100-244, tests/audiences_test.py:11-88

Operational Lifecycle

The lifecycle of an audience typically begins with creation and ends with removal. The following sequence diagram illustrates the synchronous creation and retrieval flow.

The sequence demonstrates the redirection from Audiences to Segments and the resulting API interaction.
Sources: resend/audiences/_audiences.py:100-111, resend/audiences/_audiences.py:149-160, tests/audiences_test.py:11-30

Pagination Logic

When listing audiences, you can control the volume of data returned using ListParams. The limit attribute must be between 1 and 100. Pagination is handled using after or before cursors, which refer to audience IDs.

params: resend.Audiences.ListParams = {
    "limit": 10,
    "after": "audience-id-xyz",
}
audiences = resend.Audiences.list(params=params)
# has_more indicates if further pages exist
if audiences["has_more"]:
    next_cursor = audiences["data"][-1]["id"]

Sources: resend/audiences/_audiences.py:46-60, examples/audiences.py:23-34

Exception Handling

The system validates that operations return content. If the Resend API returns an empty response for an expected object, the SDK raises a NoContentError.
Sources: tests/audiences_test.py:32-38, tests/audiences_async_test.py:133-140

Usage Example

The following snippet demonstrates creating an audience and subsequently removing it.

import resend

# Create an audience
audience = resend.Audiences.create({"name": "New Audience"})
print(f"ID: {audience['id']}")

# Remove the audience
resend.Audiences.remove(id=audience['id'])

Sources: examples/audiences.py:11-40

Audiences Management provides a unified interface for organizing contact lists. While developers should migrate to using the Segments class directly, the Audiences module maintains backward compatibility by aliasing all functionality to the newer implementation.
Sources: resend/audiences/_audiences.py:100-111