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
| Name | In | Type | Required | Description |
|---|
| projectId | query | string (uuid) | optional | When 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
| Field | Type | Required | Description |
|---|
| domains | object[] | required | |
404PROJECT_NOT_FOUND — projectId outside the org, or (without domains.manage) a project the caller cannot open
| Field | Type | Required | Description |
|---|
| error | string | required | |
500Internal server error
| Field | Type | Required | Description |
|---|
| error | string | required | |
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
| Field | Type | Required | Description |
|---|
| domain | string | required | |
| projectId | string | optional | Project the domain belongs to. Required when the org has more than one project. |
Responses
201The created domain
| Field | Type | Required | Description |
|---|
| domain | object | required | |
400Domain is required
| Field | Type | Required | Description |
|---|
| error | string | required | |
404PROJECT_NOT_FOUND
| Field | Type | Required | Description |
|---|
| error | string | required | |
409Domain already registered
| Field | Type | Required | Description |
|---|
| error | string | required | |
422PROJECT_REQUIRED — several projects and no projectId
| Field | Type | Required | Description |
|---|
| error | string | required | |
500Internal server error
| Field | Type | Required | Description |
|---|
| error | string | required | |
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
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Responses
200Branded tracking host
| Field | Type | Required | Description |
|---|
| domainId | string | required | |
| host | string | required | |
| status | string | required | ("pending" | "active" | "failed") |
| httpsStatus | string | required | ("pending" | "active") |
| dnsRecords | any[] | required | |
| dnsRecordStatuses | any[] | required | |
| lastCheckedAt | any | required | |
| verifiedAt | any | required | |
404Domain not found
| Field | Type | Required | Description |
|---|
| error | string | required | |
409Domain is not registered on its active provider
| Field | Type | Required | Description |
|---|
| error | string | required | |
422The active provider has no branded tracking host
| Field | Type | Required | Description |
|---|
| error | string | required | |
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
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Request Bodyrequired
| Field | Type | Required | Description |
|---|
| reportAddress | any | required | |
Responses
200Domain with the updated DMARC state
| Field | Type | Required | Description |
|---|
| id | string | required | |
| domain | string | required | |
| dmarc | object | required | |
400reportAddress must be a string or null
| Field | Type | Required | Description |
|---|
| error | string | required | |
403Requires domains.manage
| Field | Type | Required | Description |
|---|
| error | string | required | |
404Domain not found
| Field | Type | Required | Description |
|---|
| error | string | required | |
422INVALID_DMARC_REPORT_ADDRESS — not one plain email address
| Field | Type | Required | Description |
|---|
| error | string | required | |
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
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Responses
200DNS records grouped by provider
| Field | Type | Required | Description |
|---|
| domainId | string | required | |
| domain | string | required | |
| providers | object[] | required | |
404Domain not found
| Field | Type | Required | Description |
|---|
| error | string | required | |
GET/api/domains/{id}
Get domain detail
Retrieve domain details including provider verification status for all registered providers.
Parameters
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Responses
200Domain with provider verifications
| Field | Type | Required | Description |
|---|
| id | string | required | |
| orgId | string | required | |
| projectId | string | required | |
| domain | string | required | |
| verificationStatus | string | required | |
| createdAt | string | required | |
| updatedAt | string | required | |
| providerVerifications | object[] | required | |
404Domain not found
| Field | Type | Required | Description |
|---|
| error | string | required | |
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
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Request Bodyrequired
| Field | Type | Required | Description |
|---|
| projectId | string | required | |
Responses
200Domain after the move
| Field | Type | Required | Description |
|---|
| id | string | required | |
| orgId | string | required | |
| projectId | string | required | |
| domain | string | required | |
| verificationStatus | string | required | |
| createdAt | string | required | |
| updatedAt | string | required | |
| providerVerifications | object[] | required | |
400projectId is required
| Field | Type | Required | Description |
|---|
| error | string | required | |
404Domain or project not found
| Field | Type | Required | Description |
|---|
| error | string | required | |
409DOMAIN_IN_USE — use cases in another project still send from this domain
| Field | Type | Required | Description |
|---|
| error | string | required | |
DELETE/api/domains/{id}
Delete domain
Remove a domain and all its provider verifications.
Parameters
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Responses
200Domain deleted
| Field | Type | Required | Description |
|---|
| deleted | boolean | required | |
404Domain not found
| Field | Type | Required | Description |
|---|
| error | string | required | |
POST/api/domains/{id}/verify
Verify domain
Trigger DNS verification for a domain across all registered providers. Updates verification status in the database.
Parameters
| Name | In | Type | Required | Description |
|---|
| id | path | string (uuid) | required | Domain ID |
Responses
200Verification results per provider
| Field | Type | Required | Description |
|---|
| domainId | string | required | |
| domain | string | required | |
| overallStatus | string | required | |
| providers | object[] | required | |
404Domain not found
| Field | Type | Required | Description |
|---|
| error | string | required | |