# Check domain DNS

`POST /api/domains/{id}/verify`

No body. Checks ownership TXT and MX separately with an eight-second DNS timeout. A 200 response may have observed.ownership or observed.mx false. domain.ready reports domain catch-all readiness. With no catch-all, a verified domain with valid MX can still accept matching active exact-address routes with active endpoints.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `domains:write`.

Audience: management.

## Parameters

### id

path parameter; required.

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "domain": {
      "$ref": "#/components/schemas/Domain"
    },
    "observed": {
      "type": "object",
      "properties": {
        "ownership": {
          "type": "boolean"
        },
        "mx": {
          "type": "boolean"
        }
      },
      "required": [
        "ownership",
        "mx"
      ]
    }
  },
  "required": [
    "domain",
    "observed"
  ]
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 404

Domain not found.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503

DNS lookup unavailable or timed out. Shared request limiting can also return 503 rate_limit_unavailable with Cache-Control: no-store.

Headers:

```json
{
  "Cache-Control": {
    "description": "Request limiter responses use no-store.",
    "schema": {
      "type": "string"
    }
  }
}
```

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/Domain

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "domain": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "mxStatus": {
      "type": "string"
    },
    "billingSuspended": {
      "type": "boolean"
    },
    "ready": {
      "type": "boolean",
      "description": "Domain catch-all readiness: ownership verified, MX valid, billing not suspended, and an active catch-all endpoint assigned. False does not rule out delivery through an active exact-address route."
    },
    "endpointId": {
      "type": [
        "string",
        "null"
      ]
    },
    "endpointName": {
      "type": [
        "string",
        "null"
      ]
    },
    "endpointStatus": {
      "type": [
        "string",
        "null"
      ]
    },
    "ownershipVerifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "lastOwnershipCheckAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "mxRecords": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "mxCheckedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    },
    "dns": {
      "type": "object",
      "properties": {
        "txtHost": {
          "type": "string"
        },
        "txtValue": {
          "type": "string"
        },
        "mxHost": {
          "type": "string"
        },
        "mxPriority": {
          "type": "integer"
        }
      },
      "required": [
        "txtHost",
        "txtValue",
        "mxHost",
        "mxPriority"
      ]
    }
  },
  "required": [
    "id",
    "domain",
    "status",
    "mxStatus",
    "billingSuspended",
    "ready",
    "endpointId",
    "endpointName",
    "endpointStatus",
    "ownershipVerifiedAt",
    "lastOwnershipCheckAt",
    "mxRecords",
    "mxCheckedAt",
    "createdAt",
    "updatedAt",
    "dns"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```
