Client Architecture & Customization

Relevant source files

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

• resend.go
• contact_imports.go
• examples/send_email_custom_client.go
• examples/send_email.go
• examples/with_pagination.go
• examples/automations.go

The Resend Go SDK organizes its functionality around a central Client struct that manages authentication, HTTP communication, and service-specific sub-clients. You interface with different Resend features—such as Emails, Contacts, and Templates—through dedicated service interfaces attached to this main client.

The architecture separates the high-level API definitions from the underlying HTTP transport logic. This separation allows you to use standard configurations for quick integration or provide custom HTTP clients for advanced requirements like specific timeouts or proxy settings.

Core Client Structure

The Client struct acts as the primary entry point for the SDK. It maintains the internal state required for API requests and provides access to specialized services.

Components of the Client

The Client encapsulates the following elements:

• Authentication: Stores the Resend API Key.
• Configuration: Manages the BaseURL and UserAgent strings.
• Services: Holds references to service interfaces like EmailsSvc, TemplatesSvc, and ContactsSvc.
• Transport: Uses a standard or custom http.Client for network requests.

Initialization Methods

You can initialize the Resend client using two primary constructors depending on your customization needs.

Standard Initialization

Use resend.NewClient(apiKey) for default settings. This constructor initializes a standard http.Client and sets the production API base URL.
Sources: examples/send_email.go:16, resend.go

Custom Client Initialization

If you require specific network behaviors, use resend.NewCustomClient(httpClient, apiKey). This allows you to inject a pre-configured http.Client with custom timeouts, transport layers, or connection pool settings.
Sources: examples/send_email_custom_client.go:19-30

Feature	NewClient	NewCustomClient
HTTP Client	Default http.Client	User-provided *http.Client
Timeout Control	Default Go timeouts	Custom Timeout attribute
Transport Layer	Standard	Custom http.Transport (e.g., MaxIdleConns)
Use Case	Rapid development	Production optimization / Enterprise proxies

Request Execution Flow

The SDK follows a structured internal flow to process API calls. Service implementations call internal Client methods to build and execute HTTP requests.

Data Flow Steps

1. Service Call: The user calls a method on a service interface (e.g., client.Emails.Send).
2. Request Building: The service implementation uses client.NewRequest to generate a standard JSON request or client.NewMultipartRequest for file uploads.
3. Header Injection: The Client automatically injects Authorization, Content-Type, and User-Agent headers.
4. Execution: The Client calls its internal Perform method, which uses the httpClient to execute the request.
5. Decoding: Perform decodes the JSON response into the provided response struct.

Service Customization & Configuration

Various API requests support additional configuration through option structs, allowing for behavior modification without altering the global client state.

Pagination

List operations (Domains, API Keys, Contacts, etc.) use ListOptions to manage large datasets through cursor-based pagination.

• Limit: Controls the number of items returned.
• After: Cursor for fetching the next page.
• Before: Cursor for fetching the previous page.
  Sources: examples/with_pagination.go:21-65, examples/send_email.go:68-87

Idempotency

For write operations, especially email sending, the SDK supports IdempotencyKey. If you retry a request with the same key within 24 hours, the API returns the original response without reprocessing the action.
Sources: examples/send_email.go:37-45, examples/inboxes.go:127-133

Specialized Request Types

The SDK handles complex payloads through specific logic:

• Multipart Requests: Used for ContactImports, allowing file uploads up to 50MB. The client manages the boundary creation and file streaming.
• Context Support: Every service method has a WithContext variant (e.g., CreateWithContext), enabling proper timeout handling and cancellation propagation within Go applications.
  Sources: contact_imports.go:138-175, examples/automations.go:18, examples/templates.go:16

Summary of Client Responsibilities

The SDK architecture ensures that the developer interacts with a clean, typed interface while the Client handles the complexities of the Resend API protocol. By providing the NewCustomClient entry point, the architecture remains flexible enough to support high-performance production environments where control over the underlying HTTP transport is critical.
Sources: resend.go, examples/send_email_custom_client.go