Mailboxes

Create

Connects a new mailbox to the workspace (a Deskhero hosted address, a forwarding address on your own domain, or a Microsoft or Google account authorized through OAuth) and attaches it to an existing group, creating the group when only a label is supplied. For Microsoft and Google the server decides import_as_knowledge and import_tickets itself and queues a background setup job that subscribes to the mailbox and imports recent mail, while a forwarding mailbox creates the email domain record if it is missing and stays in require-forward state until the DNS setup is verified.

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

Authorisation: Minimum role: ADMIN

Request arguments

Name	Type	Source
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