Domains are part of Identity. A domain belongs to the organization, not to one persona — two identities can send from the same domain.
external) or mint the organization’s system subdomain (system), then publish the DNS records the API hands back.
Three readiness tracks
Verification is not one boolean. A domain advances along three independent tracks, and each gates a different capability:
A send is refused with a retryable
job_not_ready until dns_status is provisioned. Receiving is unaffected by dns_status and waits on inbound_status.
The domain object
string
Unique id (e.g.
dom_01H...).string
Always
domain.string
The fully-qualified name, lowercase, no trailing dot.
string
external (a domain you own) or system (a subdomain minted for the org).string
Overall lifecycle state of the domain record —
pending_dns, active, or failed.string
Mail-sending track. See the table above.
string
Mail-receiving track.
string
App/HTTP track.
object[]
The DNS records to publish. Same shape as List DNS records.
string | null
When verification last ran.
string
Creation timestamp.
Connect a domain
POST /v1/domains — scope agents:write
Idempotent on name: connecting a domain that already exists returns the existing record rather than a duplicate.
string
external (a domain you own), system (a subdomain minted under the org slug), or purchased. Defaults to external. purchased is accepted by the schema but answers 501 feature_not_configured — there is no outbound payment path to a registrar.string
The domain to connect. Required for
kind: "external"; omit for system and the API mints the subdomain.boolean
Also request inbound (MX) records. Defaults to
true.validation_failed (400) when name is not a valid FQDN or kind is unknown; insufficient_scope (403) without agents:write.
List domains
GET /v1/domains — scope agents:read
integer
Page size. See Pagination.
string
Cursor from the previous page.
Retrieve a domain
GET /v1/domains/{id} — scope agents:read
Returns the domain object. not_found (404) if the id does not belong to your organization.
Verify a domain
POST /v1/domains/{id}/verify — scope agents:write
Re-runnable. Each readiness track advances on its own, so calling verify after publishing only the SPF/DKIM records moves dns_status and leaves inbound_status where it was. The domain object comes back as the answer — read the three status fields to see what changed.
not_found (404); insufficient_scope (403). A track that is still unpublished is not an error: it simply stays pending.
List DNS records
GET /v1/domains/{id}/records — scope agents:read
Always allowed on every kind — reading the zone is never the dangerous half.
string
TXT, CNAME, or MX.string
The record host, relative to the registrable zone.
string
The record value.
integer | null
MX priority;
null for TXT and CNAME.boolean
true for records the platform owns — DKIM, _dmarc, and the inbound MX. An agent may read a managed record and must never edit or delete it: removing the DKIM record breaks the signature on its own mail.Delete a domain
DELETE /v1/domains/{id} — scope agents:write
Returns the standard deleted envelope. Inboxes on the domain stop delivering; released addresses are not reusable until the domain is reconnected and re-verified.
Email & SMS
Give a persona an inbox on this domain.