Custom Client Configurations

Relevant source files

The following files were used as context for generating this wiki page:

• src/config.rs
• src/lib.rs
• src/client.rs
• README.md
• Cargo.toml
• CHANGELOG.md

Custom Client Configurations allow you to modify the behavior of the Resend SDK by adjusting base URLs, HTTP client settings, and rate limits. The library provides a ConfigBuilder to facilitate these changes, enabling the use of proxies, test servers, or specialized HTTP configurations. Sources: src/config.rs:25-30, src/lib.rs:72

The configuration system centralizes how requests are built and sent to the Resend API. It manages authentication via API keys, sets the User-Agent header based on crate versioning, and implements mandatory rate limiting for asynchronous environments. Sources: src/config.rs:114-135, README.md:33-40

Configuration Architecture

The architecture relies on the Config struct, which holds the necessary state for making API calls. This state includes the reqwest::Client, the base_url, and the api_key. The Config struct is wrapped in an Arc when distributed to various service modules like EmailsSvc or ContactsSvc, ensuring that configuration is shared efficiently across the SDK. Sources: src/config.rs:90-104, src/lib.rs:88-105

Client Initialization Flow

You can initialize the client using several methods. The Resend::default() method looks for environment variables, while ConfigBuilder allows for explicit code-based configuration.

The diagram shows the transition from initialization methods to a functional Resend client instance. Sources: src/config.rs:32-45, src/lib.rs:30-35, README.md:33-35

The ConfigBuilder Component

The ConfigBuilder provides a fluent interface for setting non-default parameters. It is particularly useful for pointing the SDK to a local WireMock server or a corporate proxy. Sources: src/config.rs:47-60

Key Configuration Options

Option	Type	Default	Description
api_key	String	Required	The Resend API key used for Bearer authentication.
base_url	Url	https://api.resend.com	The root URL for all API requests. Can be overridden via RESEND_BASE_URL.
client	reqwest::Client	Client::default()	The underlying HTTP client used to execute requests.
rate_limit	u32	9	Maximum requests per second. Set via RESEND_RATE_LIMIT.

Sources: src/config.rs:70-85, src/config.rs:120-125, README.md:33-40

Rate Limiting Logic

The SDK implements internal rate limiting to prevent 429 Too Many Requests errors from the Resend API. This is handled by the governor crate in asynchronous contexts. The default limit is set to 9 requests per 1.1 seconds to stay safely under Resend's 10 requests per second limit. Sources: src/lib.rs:8-15, src/config.rs:126-135

Rate Limit Mechanism

When using the asynchronous client, every request passed through Config::send must wait for the rate limiter.

The sequence diagram illustrates how the rate limiter intercepts calls before they reach the network. Sources: src/config.rs:165-175, src/lib.rs:16-20

Customizing the HTTP Client

You can provide a pre-configured reqwest::Client to the ConfigBuilder. This allows you to set custom timeouts, default headers, or specific TLS backends (e.g., rustls vs native-tls). Sources: src/config.rs:32-40, Cargo.toml:19-21

Example: Custom Timeout and Base URL

let http_client = reqwest::Client::builder()
     .timeout(std::time::Duration::from_secs(10))
     .build()
     .unwrap();

let config = ConfigBuilder::new("re_your_key")
    .base_url("http://localhost:8080".parse().unwrap())
    .client(http_client)
    .build();

let resend = Resend::with_config(config);

Sources: src/config.rs:32-45, CHANGELOG.md:315

Path Handling in Base URLs

The Config object ensures that paths provided in the base_url are preserved. If a proxy URL like https://proxy.example.com/resend is used, the SDK correctly appends API endpoints (e.g., /emails) to the existing path. Sources: src/config.rs:154-159, CHANGELOG.md:25-26

URL Construction Logic

1. Trim trailing slashes from the base_url path.
2. Trim leading slashes from the endpoint path.
3. Join them with a single /.
4. Apply bearer_auth and USER_AGENT headers.

Sources: src/config.rs:154-162

Summary

Custom Client Configurations provide the flexibility needed for complex environments. By utilizing the ConfigBuilder, you can inject custom HTTP clients for specific networking requirements, override the API base URL for testing or proxying, and tune rate limits for high-throughput applications. This configuration is shared across all SDK services, ensuring consistent behavior across the entire library. Sources: src/config.rs:25-30, src/lib.rs:12-25