Delete a domain
Deletes a custom domain you own and tears down its authenticated sending.
Deletes a custom domain you own and tears down its authenticated sending. A domain with no inboxes is removed immediately and returns 204 with an empty body. A domain that still owns inboxes is refused with a structured 409 (code: cascade_confirmation_required) whose error.details carry requiresCascadeConfirmation: true plus the exact inboxes and messages counts a delete would remove, so you can confirm before destroying data. Re-send with cascade=true — as the ?cascade=true query parameter or a JSON body {"cascade": true} (the query wins when both are present) — to delete the domain together with all of its inboxes and their threads, messages, and attachments in one atomic transaction; compliance and audit records are retained with their inbox reference nulled. The {domain} path segment is the domain name, the included dairo.app domain cannot be deleted, and the call requires domains:write with a limit of 20 deletes per hour.
Scope: domains:write. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | yes | The domain name, such as yourapp.com. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
cascade | boolean | no | When true, also delete every inbox on this domain and all of their messages/threads/attachments in one atomic, org-scoped transaction. Required to delete a domain that still owns inboxes. |
Response
204 Success, no body.
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
409 | The resource already exists or its state does not allow this (duplicate_resource or a condition-specific code). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |
Create a domain and its DNS records
Registers a domain you own for authenticated sending and inbound receiving, and returns the created domain object with the records array to publish in DNS.
Recheck a domain's DNS records
Re-checks the DNS records for a pending domain and updates both the domain's status and each record's status to match what is currently published.