Using a Custom HTTP Client
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Java SDK allows you to replace the default HTTP layer with a custom implementation. This feature enables advanced configurations such as custom TLS settings, shared connection pools, or request interceptors for logging and monitoring.
By default, the SDK uses an internal implementation of the IHttpClient interface backed by OkHttp. You can provide your own implementation during the initialization of the Resend client to gain full control over how the SDK communicates with the Resend API.
Sources: README.md:83-86, src/main/java/com/resend/core/net/impl/HttpClient.java:18-22
Architecture and Integration
The SDK architecture separates the service logic from the network transport layer. The Resend entry point manages an instance of IHttpClient, which all specific services (e.g., Emails, Domains, API Keys) share to perform network operations.
Component Relationships
The following diagram illustrates how a custom HTTP client integrates into the SDK service hierarchy.
This flow shows that the Resend.Builder injects the client into the main Resend instance, which then propagates it to all sub-services.
Sources: src/main/java/com/resend/Resend.java:42-55, src/main/java/com/resend/core/service/BaseService.java:48-60
The IHttpClient Interface
To implement a custom client, you must implement the IHttpClient<String> interface. This interface defines the contract for standard REST requests and multipart uploads.
| Method | Description |
|---|---|
perform | Executes standard HTTP requests (GET, POST, PATCH, DELETE). Supports payloads, media types, and RequestOptions. |
performMultipart | Handles file uploads using multipart/form-data. Accepts File objects or raw byte[]. |
Sources: src/main/java/com/resend/core/net/IHttpClient.java:15-104
Implementing a Custom Client
You have two primary ways to customize the HTTP layer: wrapping the existing OkHttp implementation or creating a completely new implementation of the IHttpClient interface.
Wrapping the Default HttpClient
If you use OkHttp, you can pass a pre-configured OkHttpClient instance to the built-in HttpClient wrapper. This is the recommended approach for adding interceptors or modifying connection settings.
OkHttpClient okHttpClient = new OkHttpClient.Builder()
.addInterceptor(chain -> {
// Custom logic here
return chain.proceed(chain.request());
})
.build();
Resend resend = Resend.builder()
.apiKey("re_123")
.httpClient(new HttpClient(okHttpClient, "https://api.resend.com"))
.build();
Sources: README.md:92-108, src/main/java/com/resend/core/net/impl/HttpClient.java:62-72
Configuration Constraints
When you provide a custom httpClient via the builder, you cannot use the builder's built-in configuration methods for timeouts, proxies, or base URLs. You must configure these settings directly on your custom client.
| Builder Method | Interaction with .httpClient() |
|---|---|
.baseUrl(String) | Prohibited: Causes IllegalStateException. |
.proxy(Proxy) | Prohibited: Causes IllegalStateException. |
.connectTimeout(Duration) | Prohibited: Causes IllegalStateException. |
.readTimeout(Duration) | Prohibited: Causes IllegalStateException. |
Sources: src/main/java/com/resend/Resend.java:310-324
Request Execution Flow
When a service method is called, it uses the BaseService.execute helper to route the request through the configured client.
The sequence shows how BaseService manages serialization and error handling while delegating the actual transport to the IHttpClient.
Sources: src/main/java/com/resend/core/service/BaseService.java:82-140
Summary
Custom HTTP clients provide the flexibility needed for enterprise environments, such as corporate proxy requirements or detailed request tracing. By implementing IHttpClient or wrapping OkHttpClient, you take full control of the network stack while maintaining the high-level service abstractions provided by the Resend Java SDK.