SDK Architecture & Design

Relevant source files

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

• resend/request.py
• resend/async_request.py
• resend/webhooks/_webhooks.py
• resend/templates/_templates.py
• resend/inboxes/drafts/_inbox_drafts.py
• README.md

The Resend Python SDK provides a structured interface for interacting with the Resend API. It abstracts complex HTTP communications into simple Python classes and methods, supporting both synchronous and asynchronous execution models. The architecture follows a resource-oriented design where major API categories like Emails, Templates, and Webhooks are represented by dedicated modules.

The SDK emphasizes developer experience through explicit typing via TypedDict and comprehensive error handling. It utilizes a centralized request layer to manage authentication, headers, and JSON serialization, ensuring consistent behavior across all API interactions.

Core Request Layer

The SDK centralizes API communication within the Request and AsyncRequest classes. These classes handle the lifecycle of an HTTP request, including header construction, payload serialization, and response validation.

Synchronous and Asynchronous Execution

The SDK supports two distinct execution paths:

1. Synchronous: Uses the requests library by default. Methods are called directly (e.g., resend.Emails.send()).
2. Asynchronous: Uses the httpx library. Methods are suffixed with _async and must be awaited (e.g., await resend.Emails.send_async()).

Sources: resend/request.py:21-28, resend/async_request.py:22-29, README.md:54-65

Request Lifecycle Flow

The following diagram illustrates how a resource method (like Templates.create) interacts with the internal request layer to reach the Resend API.

Resource Modules

The SDK organizes functionality into resource-specific classes. Each class provides static methods that map to specific API endpoints.

Module Structure Examples

Resource	Class	Primary Responsibilities
Templates	Templates	Creating, publishing, and duplicating email templates.
Webhooks	Webhooks	Managing endpoints and verifying incoming event signatures.
Inboxes	InboxDrafts	Managing email drafts within specific inboxes.

Sources: resend/templates/_templates.py:21-25, resend/webhooks/_webhooks.py:19-25, resend/inboxes/drafts/_inbox_drafts.py:22-25

Authentication and Configuration

You configure the SDK by setting global attributes on the resend module. The most critical configuration is the api_key.

• API Key: Used for the Authorization header as a Bearer token.
• Base URL: Defaults to https://api.resend.com.
• HTTP Clients: You can override default_http_client or default_async_http_client to customize timeouts or connection pooling.

Sources: resend/request.py:85-89, resend/async_request.py:86-90, README.md:23-27

Header Management

The SDK manages three distinct categories of headers during the request/response cycle:

1. Identity Headers: Authorization and User-Agent are added to every outgoing request.
2. Optional Headers: Idempotency-Key and x-batch-validation are added if provided in the method options.
3. Injected Headers: The SDK injects http_headers (containing rate limit info) into the dictionary returned to the user.

Sources: resend/request.py:83-96, resend/request.py:146-150

Webhook Verification Logic

The Webhooks.verify method implements a manual HMAC-SHA256 signature validation to ensure payloads received from Resend are authentic. It follows a multi-step security protocol.

Error Handling

The SDK validates the response status code and the Content-Type. If the API returns a status code ≥ 400 or a non-JSON response, the SDK raises specific exceptions defined in resend.exceptions.

• NoContentError: Raised when an expected response body is empty.
• ResendError: Generic base class for API errors, containing the status code and message.
• raise_for_code_and_type: A utility that maps API error types to Python exceptions.

Sources: resend/request.py:47-64, resend/request.py:126-132

Summary

The Resend Python SDK architecture relies on a robust, generic request layer that facilitates both synchronous and asynchronous operations. By abstracting HTTP complexity and providing typed resource interfaces, it allows developers to interact with email templates, webhooks, and inbox drafts using idiomatic Python patterns while maintaining high standards for security and error resilience.