Mailboxes

Get one

Returns one mailbox together with a setup block: whether an import is still running and, for mailboxes on your own domain, the address to forward to plus the state of each required DNS record. The DNS records are resolved live (cached per domain), so this is slower than the plain listing.

GET /api/{tenant:minlength(2)}/v{version:apiVersion}/mailboxes/{id}

Authorisation: Minimum role: USER

Request arguments

Name	Type	Source
id	Int32

Request body example

Response

Status: 200 (OK)
Type: DTO_mailbox

Wrapper: DTO_response_wrap

Other statuses: 400 (BadRequest), 403 (Forbidden)

Response body example

DTO_mailbox

Name	Type	ReadOnly	Description
oauth2	DTO_external_auth_oauth2		Oauth2
group	DTO_reference		Group
setup	DTO_mailbox_setup	ReadOnly	Setup
created_by	DTO_reference_user	ReadOnly	Created by
last_updated_by	DTO_reference_user	ReadOnly	Last updated by
id	Int32		Id
email_address	String		Email address
type	ENUM mailbox_type		Type
status	ENUM mailbox_status	ReadOnly	Status
import_as_knowledge	Boolean	ReadOnly	Import as knowledge
import_tickets	Boolean	ReadOnly	Import tickets
created	DateTime	ReadOnly	Created
last_updated	DateTime	ReadOnly	Last updated

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_dns_setup

Name	Type	Description
type	ENUM dns_record_type	Leave empty on input
status	ENUM dns_setup_status	Status
host_value	String	Host value
data	String	Data

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 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

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

Generated Aug 4, 2026 18:37