Mailboxes
List domains
Returns the mailboxes grouped by email domain and by type, which is what the mailbox settings page lists.
For domains that use forwarding it also resolves the required DNS records live, including a recommended SPF change, and reports the domain as verified or pending, so the call can take a while (the DNS lookups are cached per domain).
GET
/api/{tenant:minlength(2)}/v{version:apiVersion}/mailboxes/list_domains
- Authorisation
- Minimum role: USER
Request arguments
Request body example
No input arguments
Response
- Status
- 200 (OK)
- Type
- DTO_mailbox_domain[]
- Wrapper
- DTO_response_wrap
- Other statuses
- 400 (BadRequest), 403 (Forbidden)
Response body example
DTO_mailbox_domain
| Name | Type | ReadOnly | Description |
|---|
| mailboxes | DTO_mailbox[] | | Mailboxes |
| domain | String | | Domain |
| type | ENUM mailbox_type | | Type |
| status | email_domain_status (nullable) | | Status |
| dns_setups | DTO_dns_setup[] | | Dns setups |
DTO_external_auth_oauth2
| Name | Type | ReadOnly | Description |
|---|
| identifier | String | | Identifier |
| authorized_account | String | ReadOnly | Authorized account |
DTO_reference
| Name | Type | ReadOnly | Description |
|---|
| id | Int32 | | The id of the reference |
| label | Object | ReadOnly | Name/Label from referenced object. |
DTO_mailbox_setup
| Name | Type | ReadOnly | Description |
|---|
| import_in_progress | Boolean | ReadOnly | Import in progress |
| dns_setups | DTO_dns_setup[] | ReadOnly | Dns setups |
| forward_to | String | ReadOnly | Forward to |
DTO_reference_user
| Name | Type | ReadOnly | Description |
|---|
| profile_pic | String | ReadOnly | Profile pic |
| email | String | ReadOnly | Email |
| id | Int32 | | Id |
| label | Object | ReadOnly | Label |
ENUM mailbox_type
| Value | Name | Description |
|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | PLATFORM_PROVIDED | Built in @tenant.deskhero.com |
| 2 | DNS | DNS setup / Custom Email domain |
| 3 | MICROSOFT | Auth2 Microsoft365 provided |
| 4 | GOOGLE | Auth2 Google provided |
ENUM mailbox_status
| Value | Name | Description |
|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | ACTIVE | ACTIVE |
| 2 | ACTIVATION_IN_PROGRESS | ACTIVATION_IN_PROGRESS |
| 101 | REQUIRE_REAUTH | REQUIRE_REAUTH |
| 102 | REQUIRE_FORWARD | REQUIRE_FORWARD |
ENUM dns_record_type
| Value | Name | Description |
|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | TXT | TXT |
| 2 | CNAME | CNAME |
ENUM dns_setup_status
| Value | Name | Description |
|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | PENDING | Waiting client to setup DNS records (or verification of it) |
| 2 | INSTALLING | Client DNS record setup completed, and verification done |
| 3 | COMPLETED | Install completed |
Generated Aug 4, 2026 18:37
