Domain Claims

Relevant source files

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

• src/Service/Domains/Claim.php
• src/Domains/Claim.php
• src/Service/Domain.php
• tests/Fixtures/Domain.php
• tests/Service/Domains/Claim.php

Domain Claims provide a mechanism for teams to claim ownership of a domain that is already verified by another team within the Resend ecosystem. This feature enables the transition of domain management between accounts by requiring DNS-based proof of control.

The system manages claims through a specialized service layer that interacts with the Resend API to initiate, retrieve, and verify claims. Each claim requires a specific DNS TXT record to be added to the domain's DNS configuration to complete the verification process.

Sources: src/Service/Domains/Claim.php:33-35, src/Domains/Claim.php:11-13, tests/Fixtures/Domain.php:107-111

System Architecture

The Domain Claim functionality is organized as a sub-service within the broader Domain management module. The Resend\Service\Domain service initializes and exposes the Resend\Service\Domains\Claim service.

Class Relationship

The following diagram illustrates the relationship between the main Service classes and the resulting Resource objects.

The Domain service acts as the entry point, providing access to the claims property which handles all claim-specific operations.
Sources: src/Service/Domain.php:11-20, src/Service/Domains/Claim.php:9-11

Data Model

The Resend\Domains\Claim class represents the data structure of a domain claim. It includes identifiers for the claim itself and the placeholder domain created on the team's account.

Claim Properties

Property	Type	Description
id	string	Unique identifier for the Domain Claim.
name	string	The domain name being claimed (e.g., example.com).
status	string	Current state of the claim (e.g., pending).
domain_id	string	ID of the placeholder domain created on your team.
region	string	AWS region used for sending (e.g., us-east-1).
record	array	The DNS TXT record required for verification.
created_at	string	Timestamp of claim creation.
expires_at	string	Timestamp when the claim window closes.

Sources: src/Domains/Claim.php:11-21, tests/Fixtures/Domain.php:107-123

DNS Verification Record

The record attribute contains a specific structure used by the user to update their DNS settings.
Sources: tests/Fixtures/Domain.php:114-119

{
  "type": "TXT",
  "name": "example.com",
  "value": "resend-domain-verification=3f8a1c2d4e5b6a7f8091a2b3c4d5e6f7",
  "ttl": "Auto"
}

Functional Operations

The Claim service provides three primary operations to manage the lifecycle of a domain takeover.

Create a Claim

You initiate a claim by providing the domain name and optional configuration parameters. This creates a placeholder domain and generates the verification record.

• Method: create(array $parameters)
• Parameters: name (required), region, open_tracking, click_tracking, tracking_subdomain.

Sources: src/Service/Domains/Claim.php:33-43, tests/Service/Domains/Claim.php:30-34

Retrieve Claim Details

You fetch the latest details of an existing claim using its unique ID. This is typically used to poll the status or retrieve the DNS record values again.

• Method: get(string $id)
• Constraint: The ID must be a non-empty string; otherwise, the service throws an InvalidArgumentException.

Sources: src/Service/Domains/Claim.php:14-23, tests/Service/Domains/Claim.php:9-13

Verify a Claim

After you add the required TXT record to the domain's DNS provider, you must trigger a verification check.

• Method: verify(string $id)
• Action: Sends a POST request to the /verify endpoint for the specific claim.

Sources: src/Service/Domains/Claim.php:50-59, tests/Service/Domains/Claim.php:41-45

Operational Flow

The following sequence diagram represents the interaction between the client application and the Resend API during a typical domain claim process.

The flow requires an external manual step where the user interacts with their DNS provider before verification can succeed.
Sources: src/Service/Domains/Claim.php:14-60, tests/Service/Domains/Claim.php:30-54

Error Handling

The service validates inputs before dispatching network requests. If you provide an empty string for a claim ID in the get or verify methods, the SDK throws an InvalidArgumentException with the message: "The domain ID must be a non-empty string."

Sources: src/Service/Domains/Claim.php:18-20, src/Service/Domains/Claim.php:52-54, tests/Service/Domains/Claim.php:17-22