SDK Initialization and Base Service
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Java SDK provides a structured interface for interacting with Resend API services. The Resend class serves as the central entry point for all service modules, managing authentication and network configurations. All feature-specific services inherit from BaseService, which provides a standardized mechanism for executing HTTP requests, handling JSON mapping, and processing API responses.
Sources: src/main/java/com/resend/Resend.java:27-31, src/main/java/com/resend/core/service/BaseService.java:16-19
SDK Architecture Overview
The SDK architecture utilizes a hierarchical structure where a central client manages shared resources used by specialized service sub-modules.
The diagram shows the relationship between the main entry point, the underlying network layer, and the service inheritance model.
Sources: src/main/java/com/resend/Resend.java:34-40, src/main/java/com/resend/core/service/BaseService.java:16-20
SDK Initialization
You initialize the SDK by creating an instance of the Resend class. This instance should be reused throughout your application because every service it returns shares the same underlying HTTP client and connection pool.
Sources: src/main/java/com/resend/Resend.java:30-31, README.md:92-92
Default Initialization
For standard configurations, you can instantiate Resend directly with an API key. This uses the default HttpClient pointing to https://api.resend.com with 10-second timeouts.
Resend resend = new Resend("re_123");
Sources: src/main/java/com/resend/Resend.java:48-50, src/main/java/com/resend/core/net/impl/HttpClient.java:23-28
Advanced Configuration with Builder
The Resend.Builder allows you to customize network parameters, including timeouts, proxies, and the base URL.
This flowchart illustrates the decision path for configuring the SDK instance.
Sources: src/main/java/com/resend/Resend.java:173-195
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | String | Required | The API key for Resend service authentication. |
baseUrl | String | https://api.resend.com | The base URL for API requests. |
connectTimeout | Duration | 10 seconds | Timeout for establishing a connection. |
readTimeout | Duration | 10 seconds | Timeout for waiting for data. |
proxy | Proxy | System defaults | The proxy server for routing requests. |
httpClient | IHttpClient | Internal HttpClient | A custom HTTP client implementation. |
Sources: src/main/java/com/resend/Resend.java:214-275, src/main/java/com/resend/core/net/impl/HttpClient.java:24-24
Core Service Architecture
All API modules (such as ApiKeys, Emails, Domains) extend the BaseService abstract class. This design ensures consistent request handling across the entire SDK.
BaseService Responsibilities
BaseService encapsulates the following core functionalities:
- Authentication: Stores and applies the
apiKeyto all requests. - Serialization: Uses a shared
ResendMapperto convert Java objects to JSON and vice-versa. - Request Execution: Provides
executemethods that wrap theIHttpClient.performcalls. - Error Handling: Validates response status codes through the
handlemethod, throwing aResendExceptionfor non-successful results (status code < 200 or >= 300).
Sources: src/main/java/com/resend/core/service/BaseService.java:20-137
Request Lifecycle
When a service method is called, the SDK follows a specific execution sequence.
The sequence diagram details the internal flow from a high-level service call to the network execution and back.
Sources: src/main/java/com/resend/core/service/BaseService.java:70-137, src/main/java/com/resend/services/apikeys/ApiKeys.java:44-47
Network Layer Implementation
The default network implementation uses okhttp3 via the HttpClient class.
Global Configuration and Versioning
The SDK maintains a USER_AGENT string formatted as resend-java/[VERSION]. The version is dynamically loaded from a resend-sdk.properties file at runtime.
Sources: src/main/java/com/resend/core/SdkVersion.java:14-25, src/main/java/com/resend/core/net/impl/HttpClient.java:27-27
Key HttpClient Features
- Shared Connection Pool: Uses a
DefaultHolderto ensure a singleOkHttpClientinstance is shared across all services by default. - Headers: Automatically adds
Accept: application/json,User-Agent, andAuthorization: Bearer [apiKey]to every request. - Multipart Support: Implements
performMultipartfor file-based operations like contact imports.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:33-35, src/main/java/com/resend/core/net/impl/HttpClient.java:85-93, src/main/java/com/resend/core/net/impl/HttpClient.java:247-260
Summary
SDK initialization centers on the Resend entry point, which configures a shared IHttpClient for the entire application. The BaseService class provides the architectural foundation for all feature modules, handling the complexities of JSON mapping and standardized error management. This structure ensures that adding new Resend API features to the SDK follows a consistent, reliable pattern.
Sources: src/main/java/com/resend/Resend.java:30-40, src/main/java/com/resend/core/service/BaseService.java:16-20