Proxy and Timeout Configurations
Relevant source files
The following files were used as context for generating this wiki page:
The Resend Java SDK provides mechanisms to customize network behavior through proxy settings and timeout durations. These configurations ensure the client operates correctly within restricted corporate environments or under specific latency requirements.
You manage these settings primarily through the Resend.Builder class. While the default Resend constructor uses sensible defaults, the builder allows you to override the base URL, connection timeouts, and proxy routing for all services generated by the client instance.
Sources: README.md:68-83, src/main/java/com/resend/Resend.java:31-36
Client Architecture and Initialization
The Resend instance serves as the central entry point for all API services. It maintains a single, shared IHttpClient instance. When you create a Resend object, it propagates the configured HTTP client to services like Emails, Domains, and ApiKeys.
Initialization Flow
The following diagram illustrates how the Resend.Builder determines which HTTP client to instantiate based on your configuration.
The diagram shows the logic within Resend.Builder to prevent combining a custom client with built-in configuration options.
Sources: src/main/java/com/resend/Resend.java:323-345, src/test/java/com/resend/ResendTest.java:54-65
Timeout Configurations
The SDK supports four distinct timeout categories using the java.time.Duration API. If you do not specify these, the SDK applies the default values defined in the underlying OkHttpClient implementation.
Timeout Categories
| Method | Description | Default Value |
|---|---|---|
connectTimeout | Sets the time to establish a connection to the server. | 10 Seconds |
readTimeout | Sets the time to wait for data packets after connection. | 10 Seconds |
writeTimeout | Sets the time to wait for sending request bodies (e.g., uploads). | 10 Seconds |
callTimeout | Sets the limit for the entire request/response lifecycle. | 0 (No Timeout) |
Sources: src/main/java/com/resend/Resend.java:246-285, src/test/java/com/resend/ResendTest.java:115-120
If you set a negative duration for any timeout, the builder throws an IllegalArgumentException.
Sources: src/main/java/com/resend/Resend.java:375-380
Proxy Configuration
You route SDK requests through a proxy by providing a java.net.Proxy object to the builder. This is essential for applications running behind corporate firewalls.
Proxy Implementation
- Instantiate a
Proxyobject with the appropriateType(typicallyHTTP) andInetSocketAddress. - Pass the
Proxyinstance toResend.Builder.proxy(). - Call
build()to generate theResendclient.
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("my.proxy.host", 8080));
Resend resend = Resend.builder()
.apiKey("re_123")
.proxy(proxy)
.build();
Sources: README.md:73-83, src/main/java/com/resend/Resend.java:287-296
Custom HTTP Client Integration
For advanced requirements like custom TLS settings, interceptors, or shared connection pools, you can provide a complete implementation of IHttpClient.
Integration Constraints
When you provide a custom httpClient, you must configure all network settings (base URL, timeouts, and proxy) directly on that client. The Resend.Builder throws an IllegalStateException if you attempt to combine httpClient(...) with methods like baseUrl(...), proxy(...), or readTimeout(...).
Sources: src/main/java/com/resend/Resend.java:328-333, src/test/java/com/resend/ResendTest.java:140-146
Internal OkHttpClient Sharing
If you only configure timeouts or a proxy without providing a custom IHttpClient, the SDK calls newBuilder() on the shared default OkHttpClient. This retains the shared connection pool and dispatcher while applying your specific overrides.
Sources: src/main/java/com/resend/Resend.java:355-373, src/test/java/com/resend/ResendTest.java:112-114
Summary of Configuration Interaction
The following sequence shows how a configured client handles a request.
The sequence demonstrates the flow of a request from the application through a configured proxy to the Resend API.
Sources: src/main/java/com/resend/core/net/impl/HttpClient.java:95-112, README.md:73-83