Getting Started

Relevant source files

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

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

The Resend Python SDK provides a structured interface for interacting with the Resend email platform. It enables developers to send emails, manage templates, handle audiences, and verify webhooks using both synchronous and asynchronous execution patterns.

This guide covers the initial environment setup, authentication, and basic usage patterns required to integrate Resend into a Python application.

Installation and Requirements

The SDK requires Python 3.7 or higher. It depends on requests for synchronous communication and typing_extensions for type safety.

Sources: setup.py:32-35, README.md:12-16

Installation Type	Command	Description
Standard	pip install resend	Installs the core SDK with synchronous support.
Async Support	pip install resend[async]	Installs the SDK with httpx for asynchronous operations.

Sources: setup.py:27-31, README.md:46-50

Setup and Authentication

To authenticate requests, you must obtain an API key from the Resend Dashboard and assign it to resend.api_key. The SDK includes the key in the Authorization header of every HTTP request as a Bearer token.

Sources: README.md:22-26, resend/request.py:73-77

The diagram shows the authentication flow where the API key is injected into the request headers before execution.
Sources: resend/request.py:70-85

Synchronous Execution Pattern

The synchronous pattern uses the Request class to perform blocking operations. By default, the SDK uses a standard HTTPClient for these calls.

Basic Email Example

import resend

resend.api_key = "re_yourkey"

params: resend.Emails.SendParams = {
    "from": "onboarding@resend.dev",
    "to": ["delivered@resend.dev"],
    "subject": "Hello",
    "html": "<strong>Welcome!</strong>",
}

email = resend.Emails.send(params)

Sources: README.md:31-43

Request Lifecycle

1. Initialization: The Request class accepts a path, parameters, and HTTP verb.
2. Header Generation: The SDK adds Accept: application/json and a User-Agent containing the SDK version.
3. Validation: If a status code ≥ 400 is returned, the SDK raises a specific error based on the API response.
4. Parsing: Successful responses are parsed from JSON and wrapped in a ResponseDict, which includes http_headers for rate limit tracking.

Sources: resend/request.py:24-42, resend/request.py:128-140

Asynchronous Execution Pattern

Async support requires the httpx library. Methods suffixed with _async (e.g., send_async, create_async) return coroutines and must be awaited.

Async Configuration

You can configure a custom async client using resend.default_async_http_client.

import resend

resend.api_key = "re_yourkey"
resend.default_async_http_client = resend.HTTPXClient(timeout=60)

Sources: README.md:69-72

Client Selection Logic

When an async method is called, the AsyncRequest class selects a client based on the following priority:

1. resend.default_async_http_client (Explicitly replaced).
2. resend.default_http_client (If it is an instance of AsyncHTTPClient).
3. Automatic HTTPXClient (If httpx is installed).

Sources: resend/async_request.py:78-90

Webhook Verification

Resend sends webhooks for events like email.sent or email.delivered. The SDK provides a verification utility to ensure incoming requests originate from Resend using HMAC-SHA256.

The sequence diagram illustrates the verification process for inbound webhooks to prevent spoofing.
Sources: examples/webhook_receiver.py:45-65

Verification Requirements

To verify a webhook, you need:

• The raw request body (payload).
• The svix-id, svix-timestamp, and svix-signature headers.
• The Webhook Secret obtained from the Resend Dashboard.

Sources: examples/webhook_receiver.py:53-65

Core API Components

The SDK is organized into modules representing Resend features.

Module	Key Operations	Documentation Link
Emails	send, get, send_async	Emails API
Templates	create, publish, list, remove	Templates API
Topics	create, get, update, list	Topics API
Webhooks	create, verify, list_events	Webhooks API

Sources: resend/topics/_topics.py:126-170, examples/templates.py:35-70, README.md:31-43

The Resend Python SDK streamlines email operations by providing a type-safe, developer-friendly interface that handles the complexities of API communication, error handling, and security verification. By supporting both synchronous and asynchronous workflows, it integrates seamlessly into diverse Python application architectures.