API · Domains

Verify a domain claim

Trigger asynchronous DNS verification and ownership transfer for a domain claim. The claim stays `pending` while verification runs; poll the retrieve endpoint for status. Once `completed`, the transferred domain has new DKIM records that must be added to DNS and verified via the standard domain verify endpoint.

POST/domains/{id}/claim/verifyFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`id` path · required	`string`	The ID of the placeholder domain created by the claim.

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/YOUR_id/claim/verify" \
  -H "Authorization: Bearer $OPENSEND_API_KEY"

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

id is the placeholder domain’s ID. The response returns the claim immediately; the DNS lookup and transfer run asynchronously, so poll Retrieve a domain claim for the result. Only server-side DNS lookups prove ownership; DNS string chunks are joined before comparison.

Once the TXT record is accepted, the previous team’s domain is removed from SES (their queued or scheduled mail blocks the transfer first) and your team’s ordinary provisioning runs with fresh DKIM keys. After the claim reaches completed, call Retrieve domain for the new records, publish them, and run Verify domain before sending. Historical emails and the old domain ID stay with the previous team.

A verified transfer that fails on the AWS side keeps status verified with a failure_reason; verifying again retries the failed step. An expired claim cannot be verified: create the claim again. Repeating this request with the same Idempotency-Key replays the first response.

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