Pagination Helper

Relevant source files

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

• resend/pagination_helper.py
• tests/pagination_helper_test.py
• resend/contacts/_topics.py
• resend/templates/_templates.py
• resend/webhooks/_webhooks.py
• resend/topics/_topics.py

The PaginationHelper class constructs URL paths with query parameters for paginated API requests. It centralizes URL formatting logic to ensure consistency across different service modules such as Contacts, Templates, and Webhooks.

Sources: resend/pagination_helper.py, resend/contacts/_topics.py:108

Core Functionality

The class provides a static method, build_paginated_path, that appends query parameters to a base API path. It handles URL encoding, filtering of null values, and merging with existing query strings.

Key Logic and Processing

• Parameter Filtering: The helper removes any keys from the parameter dictionary that have a None value.
• URL Encoding: It converts dictionary keys and values into URL-encoded strings to ensure special characters do not break the request.
• Path Merging: If the base path already contains a query string (identified by ?), it appends new parameters using &. Otherwise, it starts the query string with ?.
• Type Conversion: It converts integer values (like limits) into string format for URL compatibility.

Sources: tests/pagination_helper_test.py:46-77, resend/pagination_helper.py

Request Construction Flow

The following diagram illustrates how the PaginationHelper transforms a base path and a parameter dictionary into a final URL string.

Diagram shows the conditional logic for path concatenation and parameter cleaning.
Sources: resend/pagination_helper.py, tests/pagination_helper_test.py:59-65

Integration with API Resources

Various modules utilize PaginationHelper to handle list operations. These modules cast their specific ListParams into dictionaries before passing them to the helper.

Supported Resources

Resource	Method	Implementation File
Contacts Topics	list(), list_async()	resend/contacts/_topics.py:108, 169
Templates	list(), list_async()	resend/templates/_templates.py:221, 290
Webhooks	list(), list_async()	resend/webhooks/_webhooks.py:292, 439
Topics	list(), list_async()	resend/topics/_topics.py:173, 237

Typical Implementation Pattern

API resources follow a standard pattern when using the helper:

1. Define a base path for the resource.
2. Cast the optional ListParams object to a dictionary.
3. Call PaginationHelper.build_paginated_path to get the final path.
4. Pass the resulting path to the request executor.

# Example pattern from resend/templates/_templates.py
base_path = "/templates"
query_params = cast(Dict[Any, Any], params) if params else None
path = PaginationHelper.build_paginated_path(base_path, query_params)
# Resulting path used in request.Request

Sources: resend/templates/_templates.py:219-223, resend/contacts/_topics.py:105-108

Standard Pagination Parameters

The helper is primarily used with ListParams structures defined across the SDK. These structures generally include the following fields:

Parameter	Type	Description
limit	int	Number of items to retrieve (typically 1-100).
after	str	Cursor ID to retrieve items after a specific point.
before	str	Cursor ID to retrieve items before a specific point.

Sources: resend/templates/_templates.py:133-143, resend/webhooks/_webhooks.py:141-152

Error Handling and Edge Cases

The implementation and associated tests verify several edge cases to prevent malformed URLs:

• Empty Params: If params is None or an empty dictionary, the helper returns the path unchanged.
• Special Characters: Parameters containing spaces or symbols (e.g., test&value) are encoded (e.g., test%26value).
• Multiple Parameters: It correctly joins multiple parameters using &.
• Pre-existing Query Strings: If a path like /api-keys?status=active is provided, adding limit=5 results in /api-keys?status=active&limit=5.

Sources: tests/pagination_helper_test.py:10-57

Summary

The PaginationHelper serves as a utility for the Resend Python SDK to manage URL generation for paginated resources. By isolating query string construction, the SDK ensures that all paginated requests across different modules handle null values and URL encoding consistently.