API · Domains

Claim a domain

Start a claim for a domain that another team has already verified. The domain is recreated under your account with fresh DKIM keys, so the previous account's DNS records cannot be reused. Returns a TXT record to add to your DNS to prove ownership. Uses the same request body as creating a domain.

POST/domains/claimFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`name` body · required	`string`	The name of the domain you want to claim.
`region` body · optional	`"us-east-1" \| "eu-west-1" \| "sa-east-1" \| "ap-northeast-1"` Default: us-east-1	The region where emails will be sent from. Possible values are us-east-1 \| eu-west-1 \| sa-east-1 \| ap-northeast-1
`custom_return_path` body · optional	`string` Default: send	For advanced use cases, choose a subdomain for the Return-Path address. Defaults to 'send' (i.e., send.yourdomain.tld).
`open_tracking` body · optional	`boolean`	Track the open rate of each email.
`click_tracking` body · optional	`boolean`	Track clicks within the body of each HTML email.
`tracking_subdomain` body · optional	`string`	The subdomain to use for click and open tracking.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/domains/claim" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"example.com"}'

Response

200 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "domain_claim",
  "id": "d91cd9bd-1176-453e-8fc1-35364d380206",
  "name": "example.com",
  "status": "pending",
  "domain_id": "a1b2c3d4-1176-453e-8fc1-35364d380206",
  "region": "us-east-1",
  "record": {
    "type": "TXT",
    "name": "example.com",
    "value": "opensend-domain-verification=abc123",
    "ttl": "Auto"
  },
  "blocked_reason": null,
  "failure_reason": null,
  "created_at": "2023-04-26 20:21:26.347412+00",
  "expires_at": "2023-05-03 20:21:26.347412+00"
}

Behavior and errors

Use a claim when Create domain returned 403 validation_error because another team on the installation registered the name, in any region. The claim creates a placeholder domain on your team: it is listed under your domains but cannot send, receive, adopt an SES identity, or run ordinary verification until the transfer completes. The response is 201 for a new claim and 200 when your team’s existing pending claim is returned unchanged (its original settings are kept).

Publish the returned record (an opensend-domain-verification=… TXT value at the domain apex), then call Verify a domain claim. The token is case-sensitive. region defaults to the installation’s default region and custom_return_path to send; open_tracking, click_tracking, and tracking_subdomain are stored for the transferred domain. TLS and capabilities are not part of a claim.

Pending and blocked claims expire after seven days; creating a claim again then issues a new token. Deleting the placeholder domain cancels a pending, blocked, or expired claim. In the dashboard, the same flow starts from Domains → Add domain, which offers Claim domain when a name is already in use.

Use a full-access credential. Unknown or foreign resources return 404. See authentication, errors, rate limits, and pagination.