Domain Verification API

Verify domain ownership via DNS for email sending, custom hostnames, webhooks, and more.

Endpoints

Method	Path	Description
POST	/v1/domain-verification/domains	Register domain
GET	/v1/domain-verification/domains	List domains
GET	/v1/domain-verification/domains/{domain_id}	Get domain details
PATCH	/v1/domain-verification/domains/{domain_id}	Revoke domain
DELETE	/v1/domain-verification/domains/{domain_id}	Delete domain
POST	/v1/domain-verification/domains/{domain_id}/verify	Verify domain
GET	/v1/domain-verification/domains/{domain_id}/history	Get verification history

POST /v1/domain-verification/domains

Register domain

Register a domain for verification. Returns DNS setup instructions.

After registration, add the DNS record to your domain to prove ownership. Then call the verify endpoint to check.

Purposes:

• email - For sending email from this domain
• custom_host - For custom hostnames/CNAMEs
• webhook - For webhook endpoint verification
• link_branding - For branded tracking links
• verify_channel - For communication channel verification
• other - General domain ownership verification

Request Body:

Field	Type	Description
domain	string	Required. Domain to verify (e.g., example.com)
purpose	string	Required. Values: email, custom_host, webhook, link_branding, verify_channel, other
verification_method	string	Values: DNS_TXT, DNS_CNAME
metadata	object	Optional metadata

Example:

{
  "domain": "example.com",
  "purpose": "email",
  "verification_method": "DNS_TXT"
}

Response:

Field	Type	Description
id	string
domain	string	Domain name (normalized to lowercase/punycode)
purpose	string	Values: email, custom_host, webhook, link_branding, verify_channel, other
status	string	Values: pending, verified, failed, revoked
verification_method	string	Values: DNS_TXT, DNS_CNAME
verification_token	string	Token to add to DNS record
dns_instructions	object	Instructions for DNS setup
verification_attempts	integer
verified_at	string
last_checked_at	string
failed_reason	string
created_at	string

Example:

curl -X POST https://api.wayscloud.services/v1/domain-verification/domains \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

GET /v1/domain-verification/domains

List domains

List all domain verifications for your account. Supports filtering by purpose and status.

Response:

Field	Type	Description
domains	array
total	integer
page	integer
page_size	integer

Example:

curl https://api.wayscloud.services/v1/domain-verification/domains \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/domain-verification/domains/

Get domain details

Get details for a specific domain verification including DNS instructions.

Response:

Field	Type	Description
id	string
domain	string	Domain name (normalized to lowercase/punycode)
purpose	string	Values: email, custom_host, webhook, link_branding, verify_channel, other
status	string	Values: pending, verified, failed, revoked
verification_method	string	Values: DNS_TXT, DNS_CNAME
verification_token	string	Token to add to DNS record
dns_instructions	object	Instructions for DNS setup
verification_attempts	integer
verified_at	string
last_checked_at	string
failed_reason	string
created_at	string

Example:

curl https://api.wayscloud.services/v1/domain-verification/domains/{domain_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

PATCH /v1/domain-verification/domains/

Revoke domain

Revoke a verified domain. Only status change to revoked is allowed.

Request Body:

Field	Type	Description
status	string	Values: revoked

Response:

Field	Type	Description
id	string
domain	string	Domain name (normalized to lowercase/punycode)
purpose	string	Values: email, custom_host, webhook, link_branding, verify_channel, other
status	string	Values: pending, verified, failed, revoked
verification_method	string	Values: DNS_TXT, DNS_CNAME
verification_token	string	Token to add to DNS record
dns_instructions	object	Instructions for DNS setup
verification_attempts	integer
verified_at	string
last_checked_at	string
failed_reason	string
created_at	string

Example:

curl -X PATCH https://api.wayscloud.services/v1/domain-verification/domains/{domain_id} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

DELETE /v1/domain-verification/domains/

Delete domain

Delete a domain verification. This is a soft delete - records are preserved for audit.

Response:

Field	Type	Description
success	boolean
message	string

Example:

curl -X DELETE https://api.wayscloud.services/v1/domain-verification/domains/{domain_id} \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/domain-verification/domains/{domain_id}/verify

Verify domain

Trigger a DNS verification check for the domain.

Performs DNS lookup to verify that the required record exists. Returns the verification result immediately.

DNS record must be in place before calling this endpoint.

Response:

Field	Type	Description
id	string
domain	string
status	string
verified	boolean
message	string
dns_records_found	array
checked_at	string

Example:

curl -X POST https://api.wayscloud.services/v1/domain-verification/domains/{domain_id}/verify \
  -H "X-API-Key: YOUR_API_KEY"

---

GET /v1/domain-verification/domains/{domain_id}/history

Get verification history

Get the verification history for a domain including all check attempts and status changes.

Response:

Example:

curl https://api.wayscloud.services/v1/domain-verification/domains/{domain_id}/history \
  -H "X-API-Key: YOUR_API_KEY"

---