Introduction to Resend Python SDK

Relevant source files

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

• setup.py
• README.md
• resend/request.py
• resend/async_request.py
• resend/topics/_topics.py
• examples/with_headers.py
• examples/webhook_receiver.py

The Resend Python SDK provides a structured interface for interacting with the Resend API to manage emails, contacts, templates, and webhooks. It supports both synchronous and asynchronous execution modes, allowing integration into various Python environments ranging from simple scripts to high-concurrency web applications.

Sources: setup.py:30-31, README.md:1-5

Core Architecture and Request Flow

The SDK acts as a wrapper around HTTP requests. It utilizes a centralized request handler to manage authentication, header injection, and error handling.

Synchronous vs Asynchronous Execution

The SDK provides two primary request handlers: Request for synchronous operations and AsyncRequest for asynchronous operations.

• Synchronous: Uses a standard HTTP client (typically requests) to perform blocking calls.
• Asynchronous: Uses httpx to perform non-blocking calls. This requires installing the async extra.

Sources: setup.py:27-29, resend/request.py:20, resend/async_request.py:21, README.md:42-45

Data Flow Diagram

The following diagram illustrates how a call from the user code travels through the SDK to the Resend API and back.

Installation and Configuration

Requirements

The SDK requires Python 3.7 or higher. Core dependencies include requests and typing_extensions. Asynchronous support requires httpx.

Sources: setup.py:13-33

Initialization

You must configure the SDK with an API key obtained from the Resend Dashboard before making requests.

import resend
resend.api_key = "re_yourkey"

Sources: README.md:17-22

Key Components

Resource Modules

The SDK organizes functionality into specialized classes that correspond to API resources. Each class typically provides methods for CRUD operations.

Resource	Description	Example File
Emails	Sends emails and retrieves email status.	README.md
Contacts	Manages audiences and contact information.	examples/contacts.py
Templates	Manages reusable email templates.	examples/templates.py
Topics	Manages subscription topics and preferences.	resend/topics/_topics.py
Webhooks	Creates and verifies webhook signatures.	examples/webhook_receiver.py

Sources: resend/topics/_topics.py:16, examples/contacts.py:11, examples/templates.py:30

Request Headers Handling

The SDK manages three distinct types of headers:

1. MIME Headers: Custom headers added to the outgoing email (e.g., X-Entity-Ref-ID).
2. HTTP Response Headers: Metadata returned by the API (e.g., rate limit information), which the SDK injects into the response dictionary under the http_headers key.
3. Inbound MIME Headers: Headers present on received emails returned in the API response body.

Sources: examples/with_headers.py:1-12, resend/request.py:147

Webhook Verification

The SDK includes utility methods to verify the authenticity of incoming webhooks from Resend. It uses HMAC-SHA256 signature validation.

Error Handling

The SDK validates API responses and raises specific exceptions based on the HTTP status code or the error name returned in the JSON body.

1. Standard Errors: The perform method checks for status codes >= 400.
2. Empty Content: If a response is expected but the body is empty, it raises NoContentError.
3. JSON Validation: If the API returns a non-JSON response when JSON is expected, the SDK raises an application_error.

Sources: resend/request.py:57-75, resend/request.py:80-84, resend/request.py:133-138

Conclusion

The Resend Python SDK provides a type-safe and consistent way to interact with Resend services. By abstracting the complexities of HTTP communication, authentication, and asynchronous client management, it allows developers to focus on application logic while ensuring secure and reliable email operations.

Sources: README.md:1-10, setup.py:30-45