---
title: "Diagnose a domain's DNS"
description: "Explain why a domain is not verified, or what could break it. `GET /api/v1/email/domains/{id}/diagnose`"
url: https://www.unitpost.com/docs/email/get-email-domains-id-diagnose
section: "Email API reference"
updated: 2026-10-13
---
# Diagnose a domain's DNS

`GET /api/v1/email/domains/{id}/diagnose`

Explain why a domain is not verified, or what could break it. Every authoritative nameserver is asked about every expected record, the email provider's view of the identity is read, and `findings` list what is wrong, most serious first, each with the concrete `fix`. Read-only: it never changes the domain; [Verify a domain](https://www.unitpost.com/docs/email/post-email-domains-id-verify) does. Shares verify's per-workspace DNS rate limit. Requires the `domains:read` capability.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

## Response fields (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | enum | yes | One of: `domain_diagnosis`. |
| `domain_id` | string | yes | — |
| `domain` | string | yes | — |
| `status` | string | yes | The domain's stored status, next to the live diagnosis. |
| `checked_at` | string | yes | — |
| `last_checked_at` | string | no | The last verify check, which this call does not change. |
| `would_verify` | boolean | yes | Whether a verify run now would mark the domain verified. |
| `zone` | string | no | The zone whose nameservers were asked; null when none was found. |
| `nameservers` | object[] | no | — |
| `provider` | object | no | The email provider's view of the sending identity. |
| `records` | object[] | yes | Every expected record, with each nameserver's answer and a `verdict` (`ok`, `partial`, `wrong`, `missing`, `unknown`). |
| `findings` | object[] | yes | What is wrong, most serious first, each with the concrete `fix`. |

## Responses

| Status | Description |
| --- | --- |
| 200 | The diagnosis. |
| 401 | Missing or invalid API key. |
| 403 | Insufficient scope. |
| 404 | Domain not found. |
| 429 | Too many DNS checks; honor Retry-After. |
| 502 | Couldn't reach the mailing engine. |

## Example request

```bash
curl -X GET 'https://www.unitpost.com/api/v1/email/domains/dom_123/diagnose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
```

## Example response (200)

```json
{
  "object": "domain_diagnosis",
  "domain_id": "domain_123",
  "domain": "string",
  "status": "queued",
  "checked_at": "2026-01-01T00:00:00.000Z",
  "last_checked_at": "2026-01-01T00:00:00.000Z",
  "would_verify": false,
  "zone": "string",
  "nameservers": [
    {
      "host": "string",
      "ips": [
        "string"
      ]
    }
  ],
  "provider": {
    "configured": false,
    "identity_exists": false,
    "dkim_status": "string",
    "mail_from_status": "string",
    "error": "string"
  },
  "records": [
    {}
  ],
  "findings": [
    {
      "code": "string",
      "severity": "blocking",
      "title": "string",
      "detail": "string",
      "fix": "string"
    }
  ]
}
```

## Links

- HTML reference (with Node.js, Python, Ruby, PHP, Laravel, Go, Java, Rust, .NET and CLI examples): https://www.unitpost.com/docs/email/get-email-domains-id-diagnose
- OpenAPI 3.1 (full schemas): https://www.unitpost.com/api/v1/openapi.json