Request Configuration & Pagination
Relevant source files
The following files were used as context for generating this wiki page:
Request Configuration and Pagination provide the foundation for interacting with the Resend API efficiently and reliably. The system allows users to customize individual network requests via standard options and navigate large result sets using cursor-based pagination logic.
Every resource method in the SDK accepts an optional configuration object as its final argument, which controls headers, timeouts, and request cancellation. For "list" operations, the SDK integrates pagination utilities to append the necessary query parameters to the API request.
Request Configuration Architecture
The SDK handles request configuration through the Resend class, which serves as the central hub for network communication. When you call a resource method, the SDK merges global configuration with per-request options before executing the fetch operation.
Request Options and Headers
The Resend class manages authentication and content-type headers by default. It allows you to override these or add custom headers for specific calls, such as tracing IDs or idempotency keys.
The diagram above illustrates how per-request options flow through the SDK to the final API call.
Sources: src/resend.ts:165-215, src/request-options.spec.ts:275-285
Configuration Parameters
Users provide configuration via the RequestOptions interface. The SDK supports the following key fields:
| Field | Type | Description |
|---|---|---|
headers | Record<string, string> | Custom HTTP headers to include in the request. |
signal | AbortSignal | An AbortController signal used to cancel the request or set timeouts. |
idempotencyKey | string | A unique string for POST requests to prevent duplicate processing. |
Sources: src/resend.ts:223-234, readme.md:105-115
Cancellation and Timeouts
The SDK utilizes the standard AbortSignal to handle request timeouts and manual cancellations. If a request is aborted, the SDK returns an application_error with a null status code. You must check signal.aborted to distinguish between a network failure and a deliberate timeout.
Sources: src/resend.ts:117-158, readme.md:118-125
Pagination Logic
Pagination in the Resend SDK uses a cursor-based approach to retrieve large collections of resources like templates, contacts, or logs.
Pagination Parameters
List methods accept a PaginationOptions object containing parameters that the SDK converts into URL query strings.
| Parameter | Type | Description |
|---|---|---|
limit | number | The maximum number of records to return in a single response. |
before | string | A cursor for use in backward pagination. |
after | string | A cursor for use in forward pagination. |
Sources: src/templates/templates.ts:91-96, src/common/utils/build-pagination-query.ts
URL Construction Flow
The SDK provides internal utilities like buildPaginationUrl and getPaginationQueryProperties to ensure query parameters are correctly formatted and appended to the resource paths.
The flowchart demonstrates the logic used to construct a paginated URL before making a GET request.
Sources: src/contacts/topics/contact-topics.ts:50-65, src/templates/templates.ts:88-96
Integration and Usage
Resource modules integrate these features consistently across the library. For example, the Templates and Contacts modules pass pagination options directly to the underlying get method of the Resend class.
Example: Paginated List Request
// Fetching a specific page of templates
await resend.templates.list(
{ limit: 25, after: 'cursor123' },
{ headers: { 'X-Request-Source': 'wiki-example' } }
);
Sources: src/templates/templates.ts:88-96, readme.md:108-112
Idempotent Requests
POST operations, such as sending emails or creating drafts, support the idempotencyKey option. The Resend.post method detects this property and automatically sets the Idempotency-Key HTTP header. This ensures that if a network failure occurs, retrying the request with the same key will not result in duplicate actions on the server.
Sources: src/resend.ts:223-234, src/inboxes/threads/emails/emails.spec.ts:195-210
Conclusion
Request Configuration and Pagination allow developers to fine-tune the SDK's behavior for production environments. By utilizing RequestOptions, applications can implement robust timeout logic and tracing. Meanwhile, the pagination system provides a standardized way to traverse large datasets across the Resend API without loading entire collections into memory.