---
title: "Check a domain now"
method: POST
path: "/domains/{domain}/check"
tags: ["domains"]
---

# Check a domain now

`POST /domains/{domain}/check`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/domains/{domain}/check`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/domains/:domain/check/post.ts> (a function with typed inputs; its response is checked against the schema)

Ask the domain's authoritative nameservers for every record it publishes and, while email is set up, where its sending identity stands (org admins only), at most once every 30 seconds for the organization. The sending identity is asked about only while the organization holds the Secure Help Desk or Notify: otherwise sending pauses (`paused`, error `products_lapsed`), and a check once the organization holds either resumes sending. A check while email is being verified brings the next automatic check forward.

## Path parameters

- `domain` string, required

## Response `200`

The domain, as the check found it.

- object
  - `data` DomainAnswer, required
    - `domain` DomainStatus, required: One of the organization's Company Domains: the entry it added, whether it still holds the domain's claim, what the domain can do, the records it publishes, each with what the last DNS check found, and that check. A domain whose claim is missing or another organization's answers `claimed: false` and reads as the entry's own verified state, never another organization's capabilities; nothing else in the answer tells the two apart.
      - `domain` string, required: The domain, lowercase.
      - `verification_method` 'dns_txt'
      - `txt_name` string: The ownership record's name: `_sparkvault.{domain}`.
      - `txt_value` string: The ownership record's value.
      - `created_at` integer: Unix seconds.
      - `verified_at` integer: Unix seconds: when the ownership record was proven.
      - `claimed` boolean, required: Whether the organization holds the domain's claim. False: the claim that proves the organization owns the domain is missing or another organization's; remove the domain and add it again to prove ownership.
      - `zone_apex` boolean, nullable, required: Whether the domain is its own DNS zone; null until a check learns it. A zone apex cannot carry a help desk; Notify can send from one.
      - `ownership` object, required
        - `status` 'verified' | 'lapsed'
        - `last_checked_at` integer, nullable
        - `last_ok_at` integer, nullable
        - `lapse_started_at` integer, nullable: The first check that found the ownership record missing; missing for 24 hours, ownership lapses.
      - `email` object, required
        - `sending` object
          - `status` 'not_requested' | 'pending_dns' | 'ready' | 'degraded' | 'failed' | 'paused'
          - `ready_at` integer, nullable
          - `last_checked_at` integer, nullable
          - `error` string, nullable: Why sending is where it is: dkim_failed, identity_missing or setup_failed (failed), dkim_record_missing, verification_interrupted or verification_pending (degraded or waiting), products_lapsed (paused while the organization holds neither the Secure Help Desk nor Notify, whose capability it is; a check once it holds either resumes sending).
        - `receiving` object
          - `status` 'not_requested' | 'pending_dns' | 'probing' | 'ready' | 'degraded'
          - `ready_at` integer, nullable
          - `last_checked_at` integer, nullable
          - `error` string, nullable
        - `mail_from` object
          - `status` 'off' | 'pending' | 'ready' | 'failed'
          - `domain` string, nullable
      - `web` object, required
        - `status` 'not_requested' | 'pending' | 'ready' | 'moved'
        - `target` string: The CNAME target every help-desk domain points at.
        - `last_checked_at` integer, nullable
      - `email_sending_ready` boolean, required
      - `email_receiving_ready` boolean, required
      - `web_ready` boolean, required
      - `help_desk_selectable` boolean, required: Whether the mail product `help_desk` may select the domain: its ownership verified, its email sending ready and its web host live, on a domain that is not a zone apex.
      - `notify_selectable` boolean, required: Whether the mail product `notify` may select the domain: its ownership verified and its email sending ready, a zone apex included.
      - `records` object[], required: Every record the domain publishes for what it set up, in the order the console shows them.
        - `id` string, required: ownership, dkim1 to dkim3, web, mail_from_mx or mail_from_spf.
        - `host` string, required
        - `type` 'TXT' | 'CNAME' | 'MX', required
        - `value` string, required
        - `purpose` string, required
        - `status` 'ok' | 'propagating' | 'missing' | 'wrong' | 'proxied' | 'unreachable' | 'not_checked', required
      - `diagnosis` object, nullable, required: The last check: the zone it found and, per record, what each authoritative nameserver answered (`observed_by_nameserver`, with an `error` naming a nameserver that did not answer). Null before any check.
    - `email_setup_available` boolean, required: Whether email setup is offered: the organization holds the Secure Help Desk or Notify, and the platform can set it up.
  - `meta` ResponseMeta: Envelope metadata present on every successful response.
    - `api_version` string
    - `request_id` string
    - `response_ms` integer
    - `timestamp` integer: Unix seconds.
    - `pools` object: Storage and bandwidth capacity snapshot for the account.
    - `billing` object
      - `past_due` boolean
    - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise.
      - `limit` integer
      - `used` integer
      - `remaining` integer
      - `resets_at` integer: Unix seconds.

## Other responses

- `401`: AUTHENTICATION_ERROR — missing or invalid credentials.
- `403`: FORBIDDEN — the caller is not an org admin.
- `404`: NOT_FOUND — the organization lists no such domain, or does not hold its claim; nothing is checked.
- `409`: CONFLICT — the domain kept changing while it was checked; try again.
- `429`: DNS_CHECK_TOO_SOON — the organization checked the domain under 30 seconds ago; `Retry-After` carries the seconds to wait and `details.resets_at` the moment. RATE_LIMIT_EXCEEDED — the account's request budget, as on every route.
- `503`: INTERNAL_ERROR — the public resolvers could not say which zone holds the domain within the check's time; nothing is recorded, so check again in a moment. EMAIL_SETUP_BUSY — the email service is busy; try again in a moment.

## Changes

- **2026-10-28** `a9a10e328ba5`: 24 info
  - the response property `error/details` became required for the status `401`
  - the response property `error/details` became required for the status `403`
  - the response property `error/details` became required for the status `404`
  - the response property `error/details` became required for the status `409`
  - …20 more
- **2026-10-28** `56d7c265a77a`: 6 breaking, 1 info
  - the response property `error/details` became nullable for the status `401`
  - the response property `error/details` became nullable for the status `403`
  - the response property `error/details` became nullable for the status `404`
  - the response property `error/details` became nullable for the status `409`
  - …3 more
- **2026-10-21** `9f5e902abd83`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/domains/:domain/check/post.md)

---

[API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)