> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# vetta identity domain & email

> Connect sending domains and run a persona's inboxes.

Two sub-groups of [`vetta identity`](/docs/cli/identity): **domains** are org-level (a domain is shared), **email inboxes** belong to a persona.

## vetta identity domain

| Command                         | Description                                  |
| ------------------------------- | -------------------------------------------- |
| `vetta identity domain connect` | Register a domain for sending and receiving. |
| `vetta identity domain list`    | List domains.                                |
| `vetta identity domain show`    | Show one domain.                             |
| `vetta identity domain verify`  | Re-check DNS and advance the status.         |
| `vetta identity domain records` | Print the DNS records you must publish.      |
| `vetta identity domain rm`      | Remove a domain.                             |

Domains are **org-level** — there is no `--identity` flag on this sub-group.

```bash theme={"system"}
vetta identity domain list --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "dom_8e9f4apc0281smp2hk7bww0x1j",
      "object": "domain",
      "name": "acme-mail.com",
      "kind": "external",
      "status": "active",
      "dns_status": "provisioned",
      "inbound_status": "failed",
      "app_connect_status": "pending",
      "records": [
        { "type": "TXT", "host": "…._domainkey", "value": "p=MIGfMA0…", "priority": null, "managed": true }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

The three status fields move independently, and that is the point — a domain can be sending (`dns_status: provisioned`) while inbound is still broken (`inbound_status: failed`). Read all three before assuming a domain is healthy.

| Command                              | Flags                                       |
| ------------------------------------ | ------------------------------------------- |
| `connect`                            | `--domain`, `--name`, `--kind`, `--receive` |
| `list`                               | `--limit`, `--after`                        |
| `show` / `verify` / `records` / `rm` | `--domain`                                  |

```bash theme={"system"}
vetta identity domain connect --domain acme-mail.com --kind external --receive
vetta identity domain records --domain dom_...     # publish these, then:
vetta identity domain verify --domain dom_...
```

`verify` is idempotent — run it as often as you like while DNS propagates.

## vetta identity email

| Command                          | Description                          |
| -------------------------------- | ------------------------------------ |
| `vetta identity email provision` | Create an inbox on an active domain. |
| `vetta identity email list`      | List a persona's inboxes.            |
| `vetta identity email send`      | Send mail as the persona.            |
| `vetta identity email messages`  | List messages on a channel.          |
| `vetta identity email rm`        | Remove an inbox.                     |

```bash theme={"system"}
vetta identity email list --identity idn_6sc5s97c5jt1ds84qngajv659p
```

```json theme={"system"}
{ "data": [], "has_more": false, "next_cursor": null }
```

| Command     | Flags                                                                        |
| ----------- | ---------------------------------------------------------------------------- |
| `provision` | `--identity`, `--address`, `--domain`, `--agent`                             |
| `list`      | `--identity`, `--limit`                                                      |
| `send`      | `--identity`, `--inbox`, `--to`, `--subject`, `--text` (`--message` synonym) |
| `messages`  | `--identity`, `--channel`, `--limit`                                         |
| `rm`        | `--identity`, `--inbox`                                                      |

```bash theme={"system"}
vetta identity email provision --identity idn_... --address ava@acme-mail.com --domain dom_...
vetta identity email send --identity idn_... --inbox inb_... \
  --to customer@example.com --subject "Your refund" --text "Processed today."
vetta identity email messages --identity idn_... --channel inb_...
```

<Warning>
  **Outbound email depends on a configured comms provider.** Where one is not configured the send surface answers `501 not_implemented` and holds no rows to read. This is a deployment state, not a bug in your call — a persona read stays healthy either way, so `identity show` succeeding tells you nothing about whether `email send` will.

  Check by attempting one send in a test org rather than assuming; a `501` here is a platform configuration answer and no retry will change it.
</Warning>

Inbound continues to work whenever the domain's `inbound_status` is healthy, independently of the outbound path.