Web domains

Available now. Domains ship with Identity, gated by the policy layer — domain purchase is approval-gated by default.

A domain is the foundation an identity’s email sits on, and the anchor for serving apps over HTTP. Vetta models a domain with two independent verification tracks that must not be conflated:

Email track

Governs whether the domain can send and receive mail. Exposed as status (overall) plus dns_status (mail DNS).

App / HTTP track

Governs whether the domain can serve an app over HTTP. Exposed as app_connect_status, entirely separate from the email track.

A domain can be fully verified for email (status: active, dns_status: provisioned) while its app track is still pending — and vice-versa. Always check the specific track for the capability you need.

Verification tracks and their states

Capability	Required track state
Create an inbox on the domain	`status: active`
Send mail	`dns_status: provisioned`
Receive mail	domain verified for inbound at the email layer (MX in place)
Serve an app over HTTP	`app_connect_status: connected`

Every organization gets a working system domain automatically. Provisioning is fire-and-forget — it runs in the background at signup and self-heals, so a usable domain is ready without any action from you.

Create at the email layer

Vetta creates the domain at the email layer with sending and receiving enabled.

Write DNS into the shared apex zone

The required SPF/DKIM/MX/DMARC records are written directly into Vetta’s shared apex zone — no manual step, because Vetta controls the zone.

Trigger verification and poll briefly

Verification is triggered immediately and polled for a short window. When it clears, the domain row is usable.

Background healing

A background sweep periodically re-verifies any domain still pending, so transient DNS propagation delays resolve themselves.

CLI

vetta identity domain list
# NAME                          KIND     STATUS   DNS_STATUS    APP_CONNECT
# acme.<vetta-apex>             system   active   provisioned   pending

Because system domains are list-only, the resulting {org-slug}.<vetta-apex> subdomain is the fastest way to get an agent sending and receiving mail — no registrar steps at all.

BYOD: connect and verify your own domain

Connecting an external domain is a two-call flow. connect returns the DNS records to add at your registrar; verify checks them and advances both tracks.

Connect the domain

Vetta returns a set of DNS records to add at your registrar. The exact set is returned dynamically — typically a TXT for SPF, TXT/CNAME for DKIM, MX for inbound, sometimes a CNAME, plus a _dmarc TXT.

CLI

vetta identity domain connect --domain acme-mail.com

// records to add at YOUR registrar (illustrative — the real set is returned to you)
[
  { "type": "TXT",   "host": "@",              "value": "v=spf1 include:... ~all" },
  { "type": "CNAME", "host": "s1._domainkey",  "value": "s1.dkim...." },
  { "type": "MX",    "host": "@",              "value": "10 inbound....", "priority": 10 },
  { "type": "TXT",   "host": "_dmarc",         "value": "v=DMARC1; p=none; ..." }
]

Add the records at your registrar

Add every returned record exactly. Propagation can take a few minutes to a few hours depending on your registrar.

Verify

CLI

vetta identity domain verify --domain acme-mail.com

Verification advances the two tracks independently:
• Company/email track: pending_dns → active
• DNS track: pending_verification → provisioned

const domain = await vetta.domains.create({
  name: "acme-mail.com",
  kind: "external",
});
// domain.records -> the DNS records to add at your registrar

await vetta.domains.verify(domain.id);

curl https://api.vetta.sh/v1/domains \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "acme-mail.com", "kind": "external" }'

curl https://api.vetta.sh/v1/domains/$DOMAIN_ID/verify \
  -H "Authorization: Bearer $VETTA_API_KEY" -X POST

A domain is an organization object, not an identity one — two personas routinely send from the same domain, and the system domain belongs to the organization (ADR-0119). Earlier drafts of this page nested these calls under /v1/identities/{id}/domains; that spelling is not served. An identity reaches a domain through the inboxes provisioned on it.

The email readiness gate

The three email-track requirements combine into a single practical rule: a domain must be verified before an inbox can send.

Action	Gate
Create an inbox	`status: active`
Send from the inbox	`dns_status: provisioned`
Receive at the inbox	verified for inbound at the email layer

A send attempted before the domain finishes verifying is not a hard failure — it returns a retryable job_not_ready. The durable runtime can retry it once verification completes rather than dropping the message.

Protected DNS records

Some records are managed by Vetta to keep deliverability and inbound routing intact. The agent cannot edit them:

_dmarc
_domainkey and *._domainkey (DKIM)
inbound MX and their associated TXT

On a system domain the entire zone is list-only — any edit attempt returns 403. On external/purchased domains you may manage your other records, but the protected set above is still off-limits to the agent.

CLI

vetta identity domain records list --domain acme-mail.com   # always allowed
vetta identity domain records set  --domain acme.<vetta-apex> ...   # 403 on system domains

Configuration reference

Verification track fields

string

Email-track lifecycle for the domain as a whole. pending_dns → active. Creating an inbox requires active.

string

Email DNS (SPF/DKIM) provisioning state. pending_verification → provisioned. Sending requires provisioned.

string

App/HTTP track state, independent of the two email fields above. Follows its own pending → connected lifecycle.

Registrar kinds

A domain’s kind records where it lives and who owns it:

kind

Auto-provisioned subdomain under Vetta’s shared apex — e.g. {org-slug}.<vetta-apex>. Created for you at signup. List-only: DNS records are managed by Vetta and cannot be edited (editing returns 403).

kind

Bring-your-own-domain (BYOD). You own the domain at your registrar; Vetta returns the DNS records to add, then verifies them.

kind

Bought through Vetta. Vetta owns registration and manages the zone on your behalf. Purchase is approval-gated by default.

Next: email

Provision inboxes on a verified domain and send mail.

Agent

Running an agent

Agent capabilities

Computer

Identity

Team

Email track

App / HTTP track

Verification tracks and their states

BYOD: connect and verify your own domain

The email readiness gate

Protected DNS records

Configuration reference

Verification track fields

Registrar kinds

Next: email

Email track

App / HTTP track

​Verification tracks and their states

​System domains: auto-provisioning at signup

​BYOD: connect and verify your own domain

​The email readiness gate

​Protected DNS records

​Configuration reference

​Verification track fields

​Registrar kinds

Next: email

Verification tracks and their states

System domains: auto-provisioning at signup

BYOD: connect and verify your own domain

The email readiness gate

Protected DNS records

Configuration reference

Verification track fields

Registrar kinds