# Domains

> A domain is an email identity you own. Verify it once to receive mail on every address.

A **domain** is the foundation of everything in Inboundr. Once you register and
verify a domain you control, every address on it becomes a programmable inbox.

## Lifecycle

<Steps>
  <Step title="Register">
    Add the domain in the console or via
    [`POST /v1/domains`](/api-reference/domains/create). Inboundr
    creates an email identity and returns the DNS records to publish.
  </Step>
  <Step title="Publish DNS records">
    Add the returned **MX** record (routes inbound mail to Inboundr) and the
    **DKIM CNAME** records (verify you own the domain) at your DNS host.
  </Step>
  <Step title="Verify">
    Inboundr re-checks DNS every few minutes. When DKIM is observed, the domain's
    `status` becomes `verified` and mail can flow. Fetching a pending domain via
    the API also triggers a fresh check.
  </Step>
</Steps>

<Warning>
  Mail is only accepted for **verified** domains. Until DNS propagates and the
  domain verifies, messages to it are rejected.
</Warning>

## Verification status

| Status | Meaning |
| --- | --- |
| `pending` | DNS records not yet observed. Publish them and wait for propagation. |
| `verified` | DKIM observed — receiving is enabled. |
| `failed` | Verification failed. Re-check your records and try again. |

## Catch-all

Every verified domain accepts mail on **any** local part by default — there's no
need to pre-create each address. Set a domain's **catch-all endpoint** to deliver
all otherwise-unrouted mail to a single [webhook endpoint](/concepts/endpoints):

```bash
curl -X PATCH https://inboundr.net/api/v1/domains/dom_123 \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "catchAllEndpointId": "ep_123" }'
```

Pass `"catchAllEndpointId": null` to clear it. An explicit
[address route](/concepts/addresses) always takes precedence over catch-all.

## Deleting a domain

Deleting a domain removes its email identity and stops mail from being processed
immediately. Stored emails are retained, but nothing new will be accepted.

<Card title="Domains API" icon="globe" href="/api-reference/domains/list">
  List, create, inspect, update catch-all, and delete domains.
</Card>

## Catch-all fan-out

A domain's catch-all works the same as an address route: attach a webhook
endpoint and mail to any address without an explicit route goes to it; with
nothing attached, unrouted mail is dropped.

```bash
curl -X PATCH https://inboundr.net/api/v1/domains/dom_123 \
  -H "Authorization: Bearer $INBOUNDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "catchAllEndpointIds": ["ep_agent_webhook"] }'
```

The single-endpoint `catchAllEndpointId` spelling still works; `[]` turns the
catch-all off.