# check-availability

Free, unauthenticated. Reports name availability, price, and complete DNS prerequisites for a candidate payer. Supplying a candidate payer is a read, not wallet authorization or a domain claim.

## Input

| Field | Required | Notes |
|---|---|---|
| `address` | yes | Full address, e.g. `scout@agentmail.example`. Local part: lowercase letters, digits, internal `.` `_` `-`. |
| `dnsSetup` | no | `manual` (default) or `automatic`; use the same mode in the purchase. |
| `payer` | for purchase readiness | Intended wallet address. Without it, readiness is blocked with `payer_required`; no purchasable quote is implied. |

## Result artifact — `mailbox_availability`

```jsonc
{
  "address": "ops@your-domain.com",
  "available": true,            // the NAME is free
  "reason": null,               // "invalid" | "reserved" | "taken" | "domain_not_supported"
  "purchasable": false,         // available AND no purchase blockers
  "purchaseBlockers": ["dns_unverified"],
  "price": { "amount": "9990000", "currency": "USDC", "display": "$9.99", "term": "1 year" },
  "domain": {
    "name": "your-domain.com",
    "kind": "custom",           // "shared" | "custom"
    "claimed": false,           // custom domain already provisioned by another tenant
    "dns": {
      "status": "unverified",   // "verified" | "unverified"
      "autoConfigurable": true, // an eligible owner may choose dnsSetup: "automatic"
      "requiredRecords": [ { "type": "MX", "host": "@", "value": "…", "priority": 10 }, … ]
    }
  }
}
```

## Semantics

- **Shared domains**: reserved role names (`abuse`, `postmaster`, `support`, `billing`, …) are never available. Readiness follows the shared domain's operational state: an active domain is ready and needs no buyer records, and a domain awaiting DNS reports `shared_domain_pending`.
- `readiness` contains `state` (`ready`, `dns_pending`, `blocked`), `reasons`, `checkedAt`, `ownership`, `dns`, and the full `records`. Each record has `type`, FQDN `name`, relative `host`, exact `value`, and nullable `priority`.
- **Custom domains**: `available` covers only the name; check `purchasable`. External domains need the exact payer-specific TXT `_daski-mail.<domain>` = `daski-mail-owner=<lowercase payer>`, in addition to the returned MX/SPF records. Another payer's TXT does not prove this payer. A managed domain uses its current wallet owner instead of TXT, and can opt into `dnsSetup: "automatic"` when `autoConfigurable` is true. Automatic mode admits a safe additive DNS plan before propagation; the paid order then configures records and waits. In manual mode its mail records must verify before payment: publicly on mainnet, and in the registrar zone on testnet, where domains exist only in the registrar sandbox. MX priorities are recommendations; the MX host and a single SPF record with the include are what verify, plus an operator-pinned DKIM record when one is configured. Sender authentication (DKIM/DMARC) is set up after purchase and never blocks it; see `get-mailbox-authentication`.
- Readiness never reports private payer state such as a creation ban; that is enforced after payment.
- `dns: lookup_unavailable` is a resolver failure, not evidence of missing records. `conflict` means incompatible DNS. Recheck after correcting the cause. No quote or ownership claim is created by this endpoint.
- In manual mode, use wallet-authorized `set-dns-record` and recheck before payment. In automatic mode, pay only after the provider confirms that the selected payer and DNS plan are eligible. A changed payer or setup mode requires a fresh readiness check.

## Also available as REST

`POST /services/mailboxes/availability` with `{ "address": "…", "payer": "0x…" }` — same response, no task row.

Pass optional `dnsSetup: "manual" | "automatic"` (default manual), using the same mode in `create-mailbox`. `purchasable` means ready for the selected purchase flow; it does not mean DNS is already verified. Automatic mode is refused for external, foreign-owned, conflicting, or externally delegated domains. Readiness and availability never write DNS.