Domain Claims Process
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/services/domains/DomainClaims.java
- src/main/java/com/resend/services/domains/model/ClaimDomainOptions.java
- src/main/java/com/resend/services/domains/model/DomainClaimResponseSuccess.java
- src/main/java/com/resend/services/domains/Domains.java
- src/main/java/com/resend/services/domains/model/AbstractDomain.java
- src/test/java/com/resend/services/domains/DomainClaimsTest.java
- src/test/java/com/resend/services/util/DomainsUtil.java
The Domain Claims Process enables users to claim a domain that another team already verified. This module manages the lifecycle of a claim, including initialization, status retrieval, and DNS-based verification.
Sources: src/main/java/com/resend/services/domains/model/ClaimDomainOptions.java:8-10, src/main/java/com/resend/services/domains/DomainClaims.java:34-39
Process Lifecycle
The claim lifecycle involves three primary actions: creating a claim, monitoring its status, and triggering verification once DNS records are updated.
Claim Initialization
You initiate a claim by providing the domain name and configuration options such as region and tracking settings. The API returns a placeholder domain ID and a specific TXT record required for verification.
Verification Flow
After adding the provided TXT record to your DNS provider, you trigger the verification process. The system then checks the DNS records to confirm ownership and transitions the claim status.
The following diagram illustrates the sequence of interactions between the client SDK and the Resend API:
Core Components
The domain claims functionality is structured into service classes and data models that define the request and response structures.
Service Methods
The DomainClaims service provides specific methods to interact with the claim endpoints. Access this service through the claims() method in the main Domains class.
| Method | HTTP Action | Endpoint | Description |
|---|---|---|---|
create | POST | /domains/claim | Initiates a claim for a previously verified domain. |
get | GET | /domains/{id}/claim | Retrieves the current state of an existing claim. |
verify | POST | /domains/{id}/claim/verify | Triggers a DNS check to finalize the claim. |
Sources: src/main/java/com/resend/services/domains/DomainClaims.java:41-68, src/main/java/com/resend/services/domains/Domains.java:101-103
Data Models
Domain claims use specialized models for request parameters and response data. These models ensure type safety and proper JSON serialization.
Configuration Options
When creating a claim, you can configure several domain-level behaviors using ClaimDomainOptions.
Claim Options Fields
The ClaimDomainOptions builder allows setting the following parameters:
| Field | Type | Description |
|---|---|---|
name | String | The domain name to claim (e.g., "example.com"). |
region | String | The AWS region where emails will be sent from. |
custom_return_path | String | The subdomain used for the return path. |
open_tracking | Boolean | Enables or disables email open tracking. |
click_tracking | Boolean | Enables or disables link click tracking. |
tracking_subdomain | String | The subdomain used for tracking links. |
Sources: src/main/java/com/resend/services/domains/model/ClaimDomainOptions.java:14-36
Success Response Structure
A successful response from the claim endpoints provides the necessary data to proceed with DNS configuration.
| Field | Type | Description |
|---|---|---|
id | String | The unique identifier for the claim itself. |
domain_id | String | The placeholder ID assigned to the domain. |
status | String | The current state (e.g., "pending"). |
record | Object | The TXT DNS record details (type, name, value, ttl). |
expires_at | String | Timestamp indicating when the claim expires if not verified. |
Sources: src/main/java/com/resend/services/domains/model/DomainClaimResponseSuccess.java:13-60, src/test/java/com/resend/services/domains/DomainClaimsTest.java:23-32
Implementation Example
You can use the following pattern to initiate a claim.
// Define claim options
ClaimDomainOptions options = ClaimDomainOptions.builder()
.name("example.com")
.region("us-east-1")
.build();
// Create the claim
DomainClaimResponseSuccess claim = resend.domains().claims().create(options);
// Retrieve verification record details
String dnsValue = claim.getRecord().getValue();
Sources: src/test/java/com/resend/services/util/DomainsUtil.java:101-105, src/main/java/com/resend/services/domains/DomainClaims.java:41-50
Error Handling
The module throws a ResendException if the ClaimDomainOptions are null or if the API returns an error status code. Validation errors, such as an invalid domain name, typically return a 422 Unprocessable Entity status.
Sources: src/main/java/com/resend/services/domains/DomainClaims.java:42-44, src/test/java/com/resend/services/domains/DomainClaimsTest.java:73-82
The Domain Claims process ensures that domain ownership transitions securely between teams while maintaining consistent mail sending configurations across the Resend platform.