Domains API
Relevant source files
The following files were used as context for generating this wiki page:
The Domains API manages custom sending domains within the Resend infrastructure. It provides functionality to create, verify, update, and delete domains, as well as handle domain claims for verified domains owned by other teams. By configuring a domain, you establish identity and improve email deliverability through SPF, DKIM, and DMARC alignment.
This module works alongside the EmailsSvc for sending and the EventsSvc for monitoring lifecycle webhooks such as domain.created or domain.updated.
Sources: src/domains.rs:18-124, src/lib.rs:88-88, src/events.rs:260-265
Core Architecture
The DomainsSvc struct implements the domain management logic. It uses an internal Arc<Config> to build and send HTTP requests to the Resend API endpoints. Each method corresponds to a specific RESTful action on the /domains resource path.
Domain Lifecycle Flow
The following diagram illustrates the typical lifecycle of a domain, from creation through verification to eventual deletion or update.
The diagram shows the transition states defined in DomainStatus.
Sources: src/domains.rs:26-80, src/domains.rs:328-335
Data Structures
The Domains API relies on several key structures to manage domain metadata and DNS configuration.
Domain Object
The Domain struct represents the primary resource. It contains identity information, regional placement, and tracking status.
| Field | Type | Description |
|---|---|---|
id | DomainId | Unique identifier for the domain. |
name | String | The domain name (e.g., example.com). |
status | DomainStatus | Current verification state. |
region | Region | AWS region used for sending (e.g., us-east-1). |
records | Option<Vec<DomainRecord>> | List of DNS records required for verification. |
open_tracking | Option<bool> | Flag for tracking email opens. |
click_tracking | Option<bool> | Flag for tracking link clicks. |
Sources: src/domains.rs:388-410, src/domains.rs:205-220
DNS Records
Resend provides specific record types needed for authentication. These are modeled as a DomainRecord enum.
Sources: src/domains.rs:372-385, src/domains.rs:223-240
API Operations
Domain Management Methods
DomainsSvc provides high-level methods for interacting with the Resend API.
create(CreateDomainOptions): Initializes a new domain.get(domain_id): Retrieves details for a specific domain.verify(domain_id): Triggers a check against the domain's DNS records.update(domain_id, DomainChanges): Modifies tracking or TLS settings.delete(domain_id): Removes the domain from the account.list(ListOptions): Returns a paginated list of all domains.
Sources: src/domains.rs:22-80
Domain Claims
Claims allow a team to take ownership of a domain that was previously verified by another entity.
| Method | Endpoint | Description |
|---|---|---|
claim | POST /domains/claim | Initiates a claim for a verified domain. |
get_claim | GET /domains/{id}/claim | Retrieves the status of a specific claim. |
verify_claim | POST /domains/{id}/claim/verify | Triggers DNS verification for the claim. |
Sources: src/domains.rs:98-123
Domain Events and Webhooks
The system generates events when domain resources change. These are parsed by try_parse_event in the events module.
Supported event types include domain.created, domain.updated, and domain.deleted.
Sources: src/events.rs:260-265, src/events.rs:651-760
Error Handling
The Domains API utilizes the standard ErrorResponse structure. Common errors specific to domains include validation_error (e.g., invalid domain format) and not_found (e.g., querying a deleted DomainId).
| Error Kind | Description |
|---|---|
ValidationError | Returned when domain options are malformed. |
NotFound | Returned when the domain ID does not exist. |
ResourceLocked | Occurs when another request is currently updating the domain. |
Sources: src/error.rs:25-150, CHANGELOG.md:120-125
Usage and Quotas
Domain creation and maintenance are subject to account-level limits. The UsageSvc provides data on domain consumption.
domains.used: The number of currently created domains.domains.limit: The maximum allowed domains for the account plan.
Sources: src/usage.rs:32-33, src/usage.rs:114-121
The Domains API provides the necessary infrastructure for managing sender identity. Successful integration requires handling domain creation, implementing DNS records provided in the Domain object, and monitoring verification status through the API or Webhooks.