Domains

9 endpoints

GET/api/domains

List domains

Retrieve sending domains the session caller may see. Without a query: callers with `domains.manage` get every org domain; others get domains in projects they can open (`accessibleProjectIds`). With `projectId`, returns only that project's domains (404 PROJECT_NOT_FOUND when the caller cannot reach it).

Parameters
NameInTypeRequiredDescription
projectIdquerystring (uuid)optionalWhen set, list only this project's domains. Callers with `domains.manage` may name any project in the org (checked via `getProjectById`); others must be able to open the project (`canOpenProject`).
Responses
200List of domains
FieldTypeRequiredDescription
domainsobject[]required
404PROJECT_NOT_FOUND — projectId outside the org, or (without domains.manage) a project the caller cannot open
FieldTypeRequiredDescription
errorstringrequired
500Internal server error
FieldTypeRequiredDescription
errorstringrequired
POST/api/domains

Add domain

Register a new domain for the organization. The domain will be normalized to lowercase and start in pending verification status.

Request Bodyrequired
FieldTypeRequiredDescription
domainstringrequired
projectIdstringoptionalProject the domain belongs to. Required when the org has more than one project.
Responses
201The created domain
FieldTypeRequiredDescription
domainobjectrequired
400Domain is required
FieldTypeRequiredDescription
errorstringrequired
404PROJECT_NOT_FOUND
FieldTypeRequiredDescription
errorstringrequired
409Domain already registered
FieldTypeRequiredDescription
errorstringrequired
422PROJECT_REQUIRED — several projects and no projectId
FieldTypeRequiredDescription
errorstringrequired
500Internal server error
FieldTypeRequiredDescription
errorstringrequired
POST/api/domains/{id}/branded-tracking

Enable branded tracking host

Create (or adopt) the provider's branded tracking host under the domain and return its DNS records and status. Open tracking on inbox mail requires it to be active over HTTPS.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Responses
200Branded tracking host
FieldTypeRequiredDescription
domainIdstringrequired
hoststringrequired
statusstringrequired("pending" | "active" | "failed")
httpsStatusstringrequired("pending" | "active")
dnsRecordsany[]required
dnsRecordStatusesany[]required
lastCheckedAtanyrequired
verifiedAtanyrequired
404Domain not found
FieldTypeRequiredDescription
errorstringrequired
409Domain is not registered on its active provider
FieldTypeRequiredDescription
errorstringrequired
422The active provider has no branded tracking host
FieldTypeRequiredDescription
errorstringrequired
PUT/api/domains/{id}/dmarc

Set the DMARC report address

Set or clear (null) the mailbox DMARC aggregate reports go to. Only changes the recommended record for a domain with no DMARC (`rua=mailto:<address>`); nothing is written to DNS and an existing record is never rewritten.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Request Bodyrequired
FieldTypeRequiredDescription
reportAddressanyrequired
Responses
200Domain with the updated DMARC state
FieldTypeRequiredDescription
idstringrequired
domainstringrequired
dmarcobjectrequired
400reportAddress must be a string or null
FieldTypeRequiredDescription
errorstringrequired
403Requires domains.manage
FieldTypeRequiredDescription
errorstringrequired
404Domain not found
FieldTypeRequiredDescription
errorstringrequired
422INVALID_DMARC_REPORT_ADDRESS — not one plain email address
FieldTypeRequiredDescription
errorstringrequired
GET/api/domains/{id}/dns-records

Get domain DNS records

Retrieve all required DNS records across providers for a domain, including human-readable explanations.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Responses
200DNS records grouped by provider
FieldTypeRequiredDescription
domainIdstringrequired
domainstringrequired
providersobject[]required
404Domain not found
FieldTypeRequiredDescription
errorstringrequired
GET/api/domains/{id}

Get domain detail

Retrieve domain details including provider verification status for all registered providers.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Responses
200Domain with provider verifications
FieldTypeRequiredDescription
idstringrequired
orgIdstringrequired
projectIdstringrequired
domainstringrequired
verificationStatusstringrequired
createdAtstringrequired
updatedAtstringrequired
providerVerificationsobject[]required
404Domain not found
FieldTypeRequiredDescription
errorstringrequired
PATCH/api/domains/{id}

Move domain to another project

Change the project a domain is attributed to. The row moves (it is not copied) and keeps its verification. Refused while a use case in another project sends from the domain.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Request Bodyrequired
FieldTypeRequiredDescription
projectIdstringrequired
Responses
200Domain after the move
FieldTypeRequiredDescription
idstringrequired
orgIdstringrequired
projectIdstringrequired
domainstringrequired
verificationStatusstringrequired
createdAtstringrequired
updatedAtstringrequired
providerVerificationsobject[]required
400projectId is required
FieldTypeRequiredDescription
errorstringrequired
404Domain or project not found
FieldTypeRequiredDescription
errorstringrequired
409DOMAIN_IN_USE — use cases in another project still send from this domain
FieldTypeRequiredDescription
errorstringrequired
DELETE/api/domains/{id}

Delete domain

Remove a domain and all its provider verifications.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Responses
200Domain deleted
FieldTypeRequiredDescription
deletedbooleanrequired
404Domain not found
FieldTypeRequiredDescription
errorstringrequired
POST/api/domains/{id}/verify

Verify domain

Trigger DNS verification for a domain across all registered providers. Updates verification status in the database.

Parameters
NameInTypeRequiredDescription
idpathstring (uuid)requiredDomain ID
Responses
200Verification results per provider
FieldTypeRequiredDescription
domainIdstringrequired
domainstringrequired
overallStatusstringrequired
providersobject[]required
404Domain not found
FieldTypeRequiredDescription
errorstringrequired