---
title: "Register a domain for verification."
method: POST
path: "/v1/domains"
tags: ["Domains"]
---

# Register a domain for verification.

`POST /v1/domains`

## Request

- Base URL: `https://api.inboxy.net`
- URL: `https://api.inboxy.net/v1/domains`
- Auth: HTTP bearer

Requires `manage` scope. Gated by the plan's `verified_domain_limit` (`cap_reached`, 403, body carries `used`/`limit`). `domain` is validated as a bare hostname (`invalid_domain`, 400); a domain already claimed by any inboxy account is rejected as a conflict (`already_claimed`, 409 — a deliberate divergence from most other create endpoints' single 400 reason, since this is a conflict with existing state rather than a malformed request). The response's `dns_records` are the TXT/SPF/DKIM records to publish; verification runs on a periodic sweep or on-demand via `POST /v1/domains/{id}/verify`. Verification only — a verified domain cannot yet be used to send mail.

## Request body

- VerifiedDomainCreate
  - `domain` string, required: Bare hostname, e.g. `mail.example.com`. No scheme, path, port, or IP literal.

## Response `201`

Created, in `pending` status.

- VerifiedDomain
  - `id` string, uuid, required
  - `domain` string, required
  - `status` 'pending' | 'verified' | 'verification_lost', required: `verified` after 3 consecutive passing checks; demoted to `verification_lost` after 2 consecutive failures once verified. Verification only — this status never grants a sending capability.
  - `txt_ok` boolean, required: Ownership TXT challenge record found and matching.
  - `spf_state` 'ok' | 'conflict' | 'missing' | 'null', nullable, required
  - `spf_suggestion` string, nullable, required: Suggested SPF record text. Null iff `spf_state` is `ok`.
  - `dkim_cname_ok` boolean, required: DKIM selector CNAME found and matching.
  - `last_checked_at` integer, nullable, required: Unix seconds.
  - `created_at` integer, required: Unix seconds.
  - `verified_at` integer, nullable, required: Unix seconds of the transition into `verified`. A re-check that keeps the domain verified, or one that fails without demoting it, never clears this. It IS cleared back to null if the domain is demoted to `pending` (e.g. by rotating its verify token) — it re-marks the transition on the next fresh verification.
  - `dns_records` object, required: The DNS records to publish at your registrar. `txt.value` is not a secret — it is meant to be published in public DNS, and (unlike a webhook's signing secret) is returned on every response, not just at creation.
    - `txt` object, required
      - `host` string, required
      - `value` string, required
    - `spf` object, nullable, required: Null once `spf_state` is `ok` — nothing left to change.
      - `host` string
      - `value` string, nullable
    - `dkim` object, required
      - `host` string, required
      - `type` 'CNAME', required
      - `value` string, required

## Other responses

- `400`: Malformed request.
- `403`: Token lacks the required scope.
- `409`: `already_claimed` — this domain is already registered by an inboxy account.

---

[API](https://skmtc.dev/inboxy/apis/inboxy-api.md) · [All operations](https://skmtc.dev/inboxy/apis/inboxy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inboxy/apis/inboxy-api/revisions/25155a8dec0f?raw)