Pagination & List Options
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Rust SDK uses a standardized approach to manage paginated data and list retrieval across various services. This system allows you to control the volume of data returned and navigate through large datasets using cursor-based pagination. It provides a generic ListOptions structure to configure request parameters and a ListResponse structure to handle paginated results.
Sources: src/list_opts.rs:24-81, src/lib.rs:114-115
List Options Architecture
The ListOptions struct serves as the primary configuration object for all "list" endpoints in the SDK. It utilizes a phantom type state machine to ensure valid pagination queries, preventing the simultaneous use of "before" and "after" markers.
Core Components
- ListOptions: A generic struct that holds query parameters including
limit,before_id, andafter_id. - Marker Traits:
TimeNotSpecified,ListBefore, andListAfterdefine the current state of the pagination request. - Other Parameters: The
otherfield allows for arbitrary key-value pairs to support endpoint-specific filters (e.g., status filters for contacts).
Sources: src/list_opts.rs:34-51, src/list_opts.rs:90-112
State Transitions for Pagination
The following diagram illustrates how ListOptions transitions between states based on the pagination method called.
The diagram shows that a user starts with a default configuration and can move into a specific pagination direction, but cannot switch between "before" and "after" once set.
Sources: src/list_opts.rs:65-112
List Parameters and Response Structure
Endpoints that return multiple items follow a consistent request/response pattern. You pass a ListOptions object to the service method, and the API returns a ListResponse<T>.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
limit | u8 | Number of items to retrieve (Min: 1, Max: 100). |
before | String | Retrieves items created before this ID. |
after | String | Retrieves items created after this ID. |
other | HashMap | Arbitrary key-value pairs for custom filtering. |
Sources: src/list_opts.rs:40-51, src/list_opts.rs:81-87
Response Structure
| Field | Type | Description |
|---|---|---|
data | Vec<T> | The list of retrieved items. |
has_more | bool | Indicates if more items are available in the dataset. |
Sources: src/list_opts.rs:118-121
Service Integration
Most service modules in the SDK implement a list method that accepts ListOptions. This provides a unified interface for managing resources like Emails, Contacts, and Templates.
Usage in Service Methods
When you call a list method, the SDK builds a GET request and appends the ListOptions as query parameters.
// Example: Listing emails with a limit
let list_opts = ListOptions::default().with_limit(10);
let response = resend.emails.list(list_opts).await?;
// Example: Navigating with cursor
let next_page = ListOptions::default()
.list_after("email_id_123")
.with_limit(20);
Sources: src/emails.rs:104-108, src/list_opts.rs:27-32
Supported Services
The following services implement the standard pagination pattern:
- EmailsSvc: Lists sent emails and attachments. Sources: src/emails.rs:104, src/emails.rs:133
- ContactsSvc: Lists audience contacts and contact properties. Sources: src/contacts.rs:102, src/contacts.rs:242
- TopicsSvc: Lists user topics. Sources: src/topics.rs:69
- TemplateSvc: Lists email templates. Sources: src/templates.rs:104
- AutomationsSvc: Lists automations and automation runs. Sources: src/automations.rs:69, src/automations.rs:115
- WebhookSvc: Lists configured webhooks and delivery attempts. Sources: src/webhooks.rs:61, src/webhooks.rs:132
Advanced Filtering
The with_other method provides a mechanism to inject additional query parameters that are not part of the standard pagination set. This is used for domain-specific filtering within the API.
// Example: Filtering contacts by status during import
let opts = ListOptions::default()
.with_other("status", serde_json::json!("completed"));
let imports = resend.contacts.list_imports(opts).await?;
Sources: src/list_opts.rs:90-95, src/contacts.rs:309-315
Sequence of a Paginated Request
The interaction between the user, the SDK, and the Resend API during a paginated request follows a synchronous or asynchronous flow depending on the selected feature.
Sources: src/list_opts.rs:34-112, src/emails.rs:104-108
Summary
The Pagination and List Options system ensures a predictable developer experience across the SDK. By using ListOptions, you manage memory and network overhead by limiting response sizes. The cursor-based markers (before and after) allow for stable navigation through datasets that may change during iteration.