Domains

Adding a Domain#

Domains are added at the org level via the API:

POST /api/v1/orgs/{orgId}/domains{"domain_name": "test.example.com"}

The TXT verification value is derived from the domain's UUID and returned as verification_record: burnerbyte-verify=<domain-uuid>.

Creating a domain immediately kicks off an asynchronous MX/TXT/SPF pass in the background, so a domain whose DNS is already in place can come back verified with no manual step. That first check is recorded with trigger_source = "auto_create".

DNS Verification#

Two DNS records must be configured:

MX Record

test.example.com.  MX  10  mail.yourserver.com.

TXT Record

test.example.com.  TXT  "burnerbyte-verify=abc123"

Verification Flow#

1. Manual trigger — Click "Re-verify DNS" or call POST /api/v1/orgs/{orgId}/domains/{domainId}/verify
2. Auto-polling — The frontend polls every 30 seconds while verification is pending
3. Background worker — The DNS recheck worker re-verifies all unverified domains every hour

Both MX and TXT must be verified before the domain can be assigned to a team — which is the prerequisite for creating any inbox on it. Inbox creation separately re-checks that MX is still verified. The server also checks SPF and records the result, but SPF is informational only and gates nothing.

Team Assignment#

After verification, assign the domain to teams:

POST /api/v1/orgs/{orgId}/teams/{teamId}/domains{"domain_id": "...", "access_level": "full"}

Access levels: full (manage the assignment + create inboxes), create_inbox (create inboxes only), or read_only (view only). Each assignment can override two settings: attachments_enabled and max_inbox_ttl. Maximum attachment size is an org-level setting only.

Bulk and Administrative Operations#

Every check — automatic on create, manual, bulk, or from the background worker — appends a row to domain_verification_history with the MX/TXT/SPF results, any lookup errors, and a trigger_source of auto_create, manual, or background.