Domains Management
Relevant source files
The following files were used as context for generating this wiki page:
Domains Management provides the interface for registering, verifying, and configuring sending domains within the Resend platform. This module allows you to manage the lifecycle of a domain, from initial creation and DNS record generation to ownership verification and tracking configuration.
The system supports both synchronous and asynchronous operations for operations such as listing domains, retrieving specific domain details, updating tracking settings, and initiating domain claims for domains verified by other accounts.
Sources: resend/domains/_domains.py:23-28, examples/domains.py:10-15
Core Architecture and Data Flow
The Domains class serves as the primary entry point for domain operations. It utilizes the request.Request utility to communicate with the Resend REST API endpoints under the /domains path.
Domain Lifecycle Flow
The following diagram illustrates the typical process of adding and verifying a domain.
Key Data Structures
The module defines specific types for requests and responses to ensure data integrity during API interactions.
| Structure | Purpose | Key Fields |
|---|---|---|
CreateParams | Parameters for registering a new domain | name, region, tracking_subdomain |
UpdateParams | Parameters for modifying existing domains | id, click_tracking, open_tracking, tls |
CreateDomainResponse | Data returned after domain creation | id, status, records, region |
ListResponse | Paginated list of domain objects | data, has_more, object |
Sources: resend/domains/_domains.py:48-155
Domain Operations
Creation and Configuration
You register a domain by providing a unique name and an optional region. Resend generates necessary DNS records, including SPF, DKIM, and tracking records, which you must configure at your DNS provider.
create_params: resend.Domains.CreateParams = {
"name": "example.com",
"region": "us-east-1",
"custom_return_path": "send",
}
domain = resend.Domains.create(params=create_params)
Sources: resend/domains/_domains.py:157-169, tests/domains_test.py:133-145
Tracking and TLS Settings
You can update a domain's tracking capabilities and security requirements.
- Open Tracking: Monitors if recipients open HTML emails.
- Click Tracking: Monitors link interactions within emails.
- TLS Options: Supports
opportunistic(attempts secure connection but falls back) orenforced(requires TLS or fails delivery).
Sources: resend/domains/_domains.py:108-129, examples/domains.py:21-27
Retrieval and Pagination
Listing domains supports cursor-based pagination using limit, after, and before parameters. The PaginationHelper builds the appropriate query strings for these requests.
Domain Claims
The DomainClaims module (accessible via Domains.Claims) handles scenarios where you need to verify a domain that is already associated with another Resend account. Claiming a domain generates fresh DKIM keys to ensure the new owner has exclusive control.
Claim Process Flow
| Method | Description |
|---|---|
create() | Initiates a claim and returns a DomainClaim object with a verification record. |
get() | Retrieves the current status and details of a pending claim. |
verify() | Triggers the asynchronous DNS check to finalize ownership transfer. |
Sources: resend/domains/claims/_domain_claims.py:38-95
Usage Monitoring
The system monitors domain resource usage against account quotas. You can retrieve usage data to see how many domains are currently used versus the account limit.
| Field | Type | Description |
|---|---|---|
used | int | Count of domains currently registered in the account. |
limit | int or None | Maximum domains allowed; None indicates unlimited. |
Sources: resend/usage/_usage.py:195-207, resend/usage/_usage.py:233-241
Conclusion
Domains Management provides a robust framework for handling email identity. By combining automated DNS record generation, flexible tracking configurations, and secure domain claiming processes, the module ensures that senders can maintain high deliverability and security standards across multiple regions and domains.
Sources: resend/domains/_domains.py:10-20, examples/domains.py:4-10