Mailboxes

Update

Replaces the mailbox settings, email address and group have to be sent on every call, and the type cannot be changed after creation. Supplying oauth2 with a new identifier stores a fresh authentication and re-queues the mailbox setup job, while import_as_knowledge and import_tickets are only applied on create and are ignored here.

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

Authorisation: Minimum role: ADMIN

Request arguments

Name	Type	Source
id	Int32
input	DTO_mailbox	Body

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